> For the complete documentation index, see [llms.txt](https://docs.lithnet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lithnet.io/okta-ma/administration/troubleshooting.md). # Troubleshooting Common failures, and the first things to check for each. Start with the error in the MIM run history, then match its time against the management agent log and the Windows Application log source `Lithnet Okta MA`. Keep two things in mind when troubleshooting. The connector does its real validation when it first connects, so problems with keys, certificates, and scopes surface when you retrieve the schema rather than when you save the page. And a scope is not a permission: the schema can retrieve cleanly, and an import or export can still be refused by Okta. ## Installation and configuration | Problem | Check | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Okta (Lithnet)** is not in the management agent list | Close and reopen Synchronization Service Manager. If it is still missing, restart the MIM Synchronization Service. This usually happens when the product was installed or upgraded while the service was running. | | The Connectivity page will not save | Fill in every field the selected authentication method requires. Check the tenant URL, the timeout, and the log path. | | It works from your workstation but fails in MIM | The service runs as a different account. Check `HTTPS_PROXY` and `NO_PROXY` in the machine environment, and restart the service after changing them. | | MIM asks for the API token again | This is normal. MIM clears encrypted parameters whenever the page is saved, so enter the token again. | | No log file is created | Check the path, and grant the MIM Synchronization Service account write access to the directory. | | Tenant URL is rejected | It must be the org root over HTTPS, with no path, query string, or fragment. Not the `-admin` hostname, an authorization server path, or the token endpoint. | ## API token | Problem | Check | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401 Unauthorized` | The token value, whether it has expired or been revoked, whether its owning account is still active, network zone restrictions on the token, and the tenant URL. | | `403 Forbidden` | The administrative access of the account that created the token, and whether it covers the object being touched. | ## OAuth | Problem | Check | | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invalid_client` | Client ID, tenant URL, whether the public key is actually registered on the app, that the `kid` matches, the signing algorithm, and certificate validity. | | `invalid_scope` or `consent_required` | Grant `okta.schemas.read` and at least one user or group scope to the service app. | | The token is issued but an API call returns `403` | Scopes only control what appears in the token. Check the app's admin role and resource set, which control what Okta permits. | | Schema retrieves but an export fails | Test the role permission for that specific operation: user, lifecycle, password, group, membership, or delete. | | The schema still shows the old access after a scope change | Retrieve the schema again. MIM never refreshes it by itself. | | Schema retrieval fails under a custom admin role | Okta doesn't publish a role permission that covers the user profile schema, which the connector needs to read. Standard roles include this access, but a custom role may not. | ## Private JWK | Problem | Check | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | The path must be fully qualified | Enter a drive-qualified or UNC path. The field takes a path, not the JWK itself. | | File not found, or access denied | Check the path, and grant the MIM Synchronization Service account read access to the file. | | The JWK is not valid | One private JWK object, not a JWKS with a `keys` array. Check `kid`, `alg`, key type, the private values, UTF-8 encoding, and the 65,536-byte limit. | | The key has no private values | The file contains the public JWK. Use the private key instead, which you saved when the key pair was created. | ## X.509 certificate | Problem | Check | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Certificate not found | The connector searches `CurrentUser\My` for the **service account**, then `LocalMachine\My`. Your own `CurrentUser` store is a different store, and the connector cannot see it. | | More than one certificate with that thumbprint | Two copies exist in the same store. Remove the one you are not using. | | The thumbprint is rejected | It must be exactly 40 hexadecimal characters. Spaces are stripped for you, so pasting from the certificate dialog is fine. | | The private key cannot be used | Grant the MIM Synchronization Service account read access to the private key (`certlm.msc` > **All Tasks** > **Manage Private Keys**). For a TPM or HSM, check the provider's own access rules, and that using the key needs no interactive step. | | The certificate is not valid | Check `NotBefore`, `NotAfter`, and the MIM server's clock. | | The key type is not supported | RSA of at least 2048 bits, or EC on P-256, P-384, or P-521. | | Okta rejects the assertion after a certificate change | A new certificate means a new thumbprint, and therefore a new `kid`. Register the new public JWK in Okta. See [key rotation](/okta-ma/authentication/key-and-certificate-rotation.md). | ## Schema and imports | Problem | Check | | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A custom user attribute is missing | Add it to the default Okta user profile, then retrieve the schema again. | | `user` or `group` is missing entirely | Grant the matching read or manage scope, then retrieve the schema again. | | Attributes are import-only when you expected to export | Grant the matching manage scope, then retrieve the schema again. | | Delta Import says it has no starting point | Run a Full Import for that object type. | | The import is slow | Compare the enumeration and processing timings in the log. Then look at the selected factor attributes, group `member`, import concurrency, object and group sizes, page size, and Okta rate limits. | | MIM's imported-object count is higher than the user count | It counts every selected object type together. The log has the separate counts. | | Expected groups are missing | Check the object type selection and the **Include built-in groups** and **Include app groups** settings. | | The import returns nothing at all | Check object type selection, whether the tenant actually holds those objects, the OAuth scopes, the role's resource set, and the group import settings. | ## Exports | Problem | Check | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | A create failed but the object exists in Okta | Exports are not transactional. A later activation or membership call failed after the create succeeded. Import and reconcile the object rather than retrying the create. | | An update to a built-in or app group fails | Only `OKTA_GROUP` groups are writable. Remove the outbound flows and deletion scoping that reach the others. | | Suspension fails | Check the user's current Okta status, and confirm you are exporting `suspended` rather than `status`. | | A permanent delete is never confirmed | Run a Full Import. A delta import cannot see an object Okta no longer holds. | | A membership change returns `403` | Membership touches both objects. Check the group and user resource sets, and both membership permissions. | | A reprovisioned user is rejected as a duplicate login | The user was deactivated, not deleted, and Okta still holds the login. Reactivate the user in Okta. | ## Passwords | Problem | Check | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Password operations never reach the connector | MIM password synchronization configuration, PCNS or the source system, the connector joins, and whether the Okta management agent is selected as a target. | | The password is rejected | Okta password policy, the user's status and authentication provider, the credential permissions on the role, and `okta.users.manage`. | | A password change is rejected but a set works | The current password MIM supplied did not match. Everything that applies to a set applies to a change as well. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.lithnet.io/okta-ma/administration/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.