Skip to content

Troubleshooting

The specific things that trip people up, and what to check first. Most "it's broken" moments are one of these.

A ticket won't turn into a plan

  • It hasn't resolved to a tenant. Only tickets that resolve to a single onboarded client proceed. Check the requester's email domain maps to a managed tenant, and that the client is onboarded and not archived/suspended.
  • The client isn't ready for execution. If discovery shows consent or permissions pending, finish GDAP + admin consent and re-run discovery. See Onboarding a client.

Plan generation seems stuck

  • Generation is a background job — for a complex ticket it can legitimately take several minutes. The Portal polls and shows progress; give it time before assuming failure.
  • If a generation job was interrupted (a deploy or host restart mid-run), it is recovered automatically and can be regenerated on demand. Reset the ticket and generate again if it's genuinely wedged.

A guidance change isn't taking effect

The live org template is the stored version, not the built-in default. After the built-in default changes, apply it with Settings → guidance → Reset to platform default. This is the single most common "why didn't my change land" cause. See Admin controls → Planning guidance.

Execution failed

  • "Object not found" right after creating it. This is Microsoft propagation lag — a just-created user or group isn't visible everywhere yet. The platform already handles this by deferring and retrying the affected step later in the run, so a single such failure usually self-heals. If a whole job failed, use Retry once the object has propagated.
  • A step was skipped. It depended on a step that failed. Fix the upstream step (or the external cause) and retry.
  • Permission / consent error. The GDAP grant or app consent for that workload isn't in place. Complete onboarding for that workload and re-run.
  • You fixed the external cause — now what? Use Retry (re-runs the failed operations) rather than regenerating, when the plan itself was correct.

Recreating a user fails with a conflict

Deleting a user in Microsoft Entra is a soft delete — the account sits in "Deleted users" for a retention window and still holds its name and addresses. Recreating the same account while the soft-deleted one exists conflicts. Purge it from Deleted users first (or expect that specific conflict). This is an Entra behaviour, not a platform fault.

An object reference is "invalid"

When a plan needs another object's directory ID (a manager, a group membership), it must carry the real ID — not a display name or email, which Microsoft rejects as an invalid identifier. For an object created earlier in the same plan, the platform resolves the ID at execution time. If you see this on a hand-edited plan, make sure references use the real object ID or the platform's live-lookup form, not a friendly name.

Everything returns 401 / "authentication required"

Operator authentication is enabled and your session isn't carrying a valid token. Sign in through the Portal. If you're an admin and locked out, the bootstrap-admin safety net (configured when enforcement was turned on) is how access is recovered — see Admin controls → Users & permissions.

A PSA pull returns nothing (or errors)

  • Base URL. Use the instance root, not an API sub-path — a trailing /api (or similar) is a common cause of 404s.
  • Scopes / permissions. The API credentials must include the scopes needed to read tickets.
  • Enabled + saved. Confirm the connector is enabled and the credentials saved; send the built-in test.
  • Config is read at startup, so if you changed connection settings, a restart-to-apply may be needed before a pull reflects them.

Still stuck?

Check the execution's per-step evidence in the Portal — each operation records what it did or the exact error it hit. That evidence, plus which step failed, is almost always enough to tell whether the cause is the tenant, a permission, or the plan itself.