# Troubleshooting

## Viewing connector logs

To view logs for the AD connector in an RPM environment:

```bash
openiam-cli log <connector-name>
```

## Updating the connector

PowerShell connectors are updated by reinstalling.

**For connectors without customizations:**

1. Back up the connector folder.
2. Uninstall the current connector via **Control Panel → Uninstall a program**.
3. Delete the connector folder.
4. Install the new connector using the same connection parameters as before.

**For connectors with customizations:** Check the connector version first in **Control Panel → Uninstall a program**. If the first two version numbers (major version) match, your existing script files are likely compatible with the new version. If the OpenIAM team created customizations for you, contact OpenIAM Support before upgrading.

## Removing the connector

Go to **Control Panel → Uninstall a program**, select the connector, right-click, and choose **Uninstall**.

The uninstaller leaves all logs, configs, and runtime-generated files in place. Remove the connector folder manually after uninstalling if that data is no longer needed.

## Verifying AD connectivity

To test the AD connection in the same way the connector does, run the following PowerShell script on the connector server:

```powershell
Import-Module ActiveDirectory
$dc = 'YOUR_DOMAIN_CONTROLLER_HOSTNAME'
$ADcred = Get-Credential

New-PSDrive -PSProvider ActiveDirectory -Server $dc -Credential $ADcred `
  -Root "" -Name IamADDrv -FormatType Canonical

if ((Test-Path IamADDrv:) -eq $false) {
  throw "Unable to connect to AD"
}
Set-Location IamADDrv:
```

## General tips

* Always use the **DNS hostname** of your domain controller in the Managed System configuration. Using an IP address can cause non-obvious errors.
* Port **9389** must be open on the domain controller for the connector to reach it.
* When connecting over LDAPS (port 636), import the CA certificate into the Java keystore:

  ```bash
  keytool -noprompt -import -v -trustcacerts -alias ldap_ca$(pwgen -s 13 1) \
    -file /path/to/ca_cert.crt \
    -keystore /usr/local/openiam/jdk/lib/security/cacerts \
    -keypass changeit -storepass changeit
  ```

  Restart the connector after importing the certificate.

## Common errors

| Error                                                                 | Possible Cause                                                                                                         | Fix                                                                                                                                                |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Cannot find newly created user X for further operations`             | Top-level error masking an earlier failure.                                                                            | Read the full error message — it contains the root cause.                                                                                          |
| `Script that was specified for execution does not exist xxx`          | A custom script is referenced in the Managed System configuration but the file does not exist in the connector folder. | Either clear the custom script reference (to use the default `Connector.ps1`) or ensure the custom script file is present in the connector folder. |
| `X: The name provided is not a properly formed account name`          | The `sAMAccountName` exceeds 20 characters.                                                                            | Shorten `sAMAccountName` to 20 characters or fewer. Review the Groovy provisioning script in the policy map for the `sAMAccountName` attribute.    |
| `Cannot process argument transformation on parameter 'Credential'...` | Password is not set in the Managed System configuration.                                                               | Set the password in the Managed System configuration.                                                                                              |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-beta.openiam.com/application-onboarding/connectors/active-directory-powershell-connector/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.