Skip to main content

Troubleshoot Onboarding

NIM Apps · Administration

Diagnose onboarding failures from the profile, onboarding record, and App configuration.

Use this guide when a person reports an onboarding error. The checks require administrator access to the onboarding profile, onboarding records, and related App configuration; end users cannot resolve these conditions themselves.

Troubleshooting pathDirect link to Troubleshooting path

Identify the symptom

URL errorConfirm the URL route and profile name use the exact configured casing
Internal error after entering an IDMatch the internal.onboarding profile value to the exact onboarding profile name
Blocked or failed sessionCheck retry limits, time windows, questions, and answer data
ID or status errorReview the onboarding record External ID and status

Inspect configuration

Review the profileCheck profile forms, answers, and onboarding timingReview the record and logsMatch the reported time and message to the affected record

Confirm the correction

Retry the affected onboarding flowConfirm the corrected URL, identifier, or profile setting resolves the reported message
Record the exact error, URL, and identifier in support notes; do not include answers or one-time passcodes.

Start with the reported messageDirect link to Start with the reported message

Ask for the exact message, the onboarding URL used, and the affected person's identifier. Then locate the onboarding profile and record before making changes. Check the profile name and current onboarding status first, because the same user-facing symptom can result from a URL mismatch, a lockout window, or an already completed record.

TroubleshootingDirect link to Troubleshooting

Problem

Internal error after entering an ID

Reported message

After entering their ID, the person receives: Internal error processing onboarding request.

Likely cause

The profile column value in the affected internal.onboarding record does not exactly match the configured onboarding profile name. The match is case-sensitive: employee does not match Employee.

The Log screen may show only onboarding request entries, such as api_onboarding_start and api_onboarding_action, without identifying the profile-name mismatch.

Resolution

  1. Locate the affected person's record in internal.onboarding.
  2. Compare its profile column value with the name of the intended onboarding profile, including capitalization.
  3. Correct the record's profile value to match exactly. For example, if the profile is named Employee, use Employee rather than employee. If a mapping populates this column, correct that mapping as well.
  4. Have the person retry onboarding with their ID and confirm the internal error no longer appears.

Problem

Bad URL

Likely cause

The URL sent to the person does not match the configured onboarding route or profile name. Onboarding URLs are case-sensitive: Onboarding and onboarding are different routes.

Resolution

  1. Compare the reported URL with the configured onboarding URL.
  2. Confirm the route and profile-name casing exactly match the configuration.
  3. Correct the communication template or user-facing link, then have the person open the corrected URL.

Problem

Expired or blocked onboarding

Likely cause

The person entered an answer or one-time passcode incorrectly too many times, or they are outside the configured onboarding start or completion window.

Resolution

  1. Open the onboarding profile and review its retry, block, and time-window settings.
  2. Review the affected onboarding record and confirm its current status.
  3. Wait for the configured block period to end or correct the record and profile settings before issuing a new onboarding attempt.

Problem

Session failed

Likely cause

Required onboarding answers are missing or configured incorrectly, or the person repeatedly entered an answer with different casing. Answers are case-sensitive.

Resolution

  1. Review the onboarding profile's configured questions and answer source.
  2. Confirm the onboarding record contains the expected answer data.
  3. Verify the answer submitted by the person matches the expected value and casing.
  4. Correct the profile or record, then retry the flow.

Problem

ID not found

Likely cause

The identifier entered by the person does not match an onboarding record, or the record's External ID does not match the intended employee identifier.

Resolution

  1. Find the affected onboarding record.
  2. Confirm its External ID matches the identifier the person should enter.
  3. Correct the record or give the person the correct identifier, then retry onboarding.

Problem

Already completed

Likely cause

The person has already completed onboarding, and the onboarding record is no longer eligible to start the flow again.

Resolution

  1. Review the onboarding record's Onboarding Status.
  2. Confirm whether the person completed the intended onboarding flow.
  3. If a new onboarding attempt is required, follow your organization's approved process for preparing a new eligible record rather than changing a completed record without review.

Use the expired or blocked message reference when reviewing the record status:

Last updated on