# Troubleshooting and help

> Resolve common sign-in, invitation, access and connection problems.

Source: https://diakrin.com/docs/troubleshooting

Start with the step that failed. For company SSO, your identity administrator checks the provider configuration and your Diakrin onboarding contact checks activation.

> [!SELF-HOSTED]
> Your installation's owner is your first contact. They manage accounts, the optional company OIDC connection and the setup checks.

## SSO will not start

Check the work email, including its exact domain. Ask whether the connection has been activated for that domain and the correct environment. A configured IdP application alone is not enough. If SSO is not active yet, follow [Connect your company SSO](/docs/sso).

## The identity provider denies sign-in

Ask IT to check application assignment, disabled-account status, MFA/Conditional Access and provider sign-in logs. For private identity services, confirm the browser has the required VPN and network access. Do not broaden company policy just to bypass an error.

## SAML assertion or redirect errors

| Symptom | First check |
| --- | --- |
| Audience or destination mismatch | Exact SP Entity ID and ACS URL from the setup packet |
| Missing email | Send the work email as `email`, or agree the exact attribute mapping |
| Invalid signature | Current certificate, signing algorithm and registered metadata |
| User changes on each sign-in | Stable NameID; avoid transient identifiers |
| Return to the wrong site | Correct environment and console return URL |
| Worked before certificate renewal | Updated metadata registered on the existing connection |

Do not share raw SAML assertions or browser network captures containing tokens. Your onboarding contact can agree a safe diagnostic method if needed.

## I signed in but cannot see my organization

Sign-in requires an existing membership, active administrator email assignment, or authorized invitation. An active assignment or invitation attaches automatically after your exact email is provider-confirmed. If the console shows **Tenant access required**, verify your email and ask the administrator to check the recipient and expiry; then retry. You can also use **Use an invitation** with their code. If you previously used password or social login, SSO may be a separate identity: follow [Existing account migration](/docs/sso/testing#existing-account-migration).

> [!SELF-HOSTED]
> Ask the owner to check that your account exists. With company OIDC, your identity-provider subject must be assigned to your account; a matching email is not enough.

## My invitation does not work

Check that it is intended for your signed-in email, unused and within its seven-day validity. Ask the administrator to revoke a misdirected code or create a new one. Older codes can be invalid after removal; rejoining needs a fresh authorized invitation.

## My project or action is missing

Select the correct organization and project. Members need explicit project assignments; project permissions can also restrict Owners or other organization roles. Ask your administrator to check live access. A “Resource unavailable” message can indicate missing permission as well as a missing resource.

If another person changed the project, reload the latest version before retrying your edit. Do not repeatedly submit an old revision.

## My coding agent cannot connect

Check the console-supplied MCP URL and the secret environment variable. Connection tokens do not expire, but a revoked token, removed membership or a role change stops them; create a new token in **Settings → AI tools**. Company SSO tokens cannot replace an MCP connection token. Follow [Connect your coding tool](/docs/builders).

> [!SELF-HOSTED]
> Your tool signs in to your installation instead of using a connection token. Sign-ins refresh on their own and end after 30 days without use or 90 days in total; sign in again when asked.

## Builder errors on a self-hosted installation

| Error | What it means | Next step |
| --- | --- | --- |
| `APP_CREATE_BLOCKED` | The installation refused to create the app. Nothing was created. | Ask the owner to fix the named prerequisite, often the audit archive (`AUDIT_EXPORT_NOT_CONFIGURED`), then run the same command again. |
| `HOST_NOT_DIAKRIN` | The address did not answer like a Diakrin installation. | Check the address. If it is right, ask the owner to route the sign-in and `/v1/platform/bootstrap` paths to the API. |
| `BUDGET_REQUIRED` | No owner-approved budget covers this app. Nothing was built or deployed. | Ask the owner to approve **Organization spending limits** in **Finish setup**, then retry. |
| `BUDGET_EXHAUSTED` | This month's approved budget is used up. Nothing was built or deployed. | Ask the owner to raise the limit, then retry. |
| `VERSION_NOT_LATEST` | Only your latest saved version can be published. | Save your change as a new version, then publish it. |
| `ROLLBACK_PLAN_REFRESH_REQUIRED` | The earlier version's plan or approval has expired. | Ask the owner to approve a fresh plan, then roll back again. |
| `ROLLBACK_SCHEMA_UNKNOWN` | Rollback is supported only for the synthetic web starter (version 1.1.0) . | Ask IT. Publish a fixed version instead. |

## The console says a connection is required

Ask your onboarding contact for the correct console URL. Check your cloud setup under **Infrastructure**.

## When your app fails

You see an error page or a failed request, or your coding agent reports a failing check. You do not need to diagnose the cloud yourself.

1. Ask your agent to read the app's recent errors with `app.logs.read`, or run `diakrin app observations read --app <app-id> --environment <environment-id> --kind logs --start <time> --end <time>` for a window of up to one hour.
2. Read the state in the answer (see the table below).
3. Find the version. Run `diakrin app status --version <version-id>` for each recent version (`diakrin app status --json` lists their ids): the version whose `image` matches the first 12 characters after `sha256:` is the one that logged the error, and the same line names its operation. The console's **Saved versions** shows image and operation for the latest version only.
4. If a new version caused the error, go back to the last version that worked with your normal publish flow, then read the window again.
5. If you are stuck, send IT the app name, environment, the time window with timezone, the error code, the request ID and the artifact digest.

| The answer says | What it means |
| --- | --- |
| **Available** | Each line's time, code and level, the request ID when your app logged one, and the artifact digest (`sha256:…`) of the version that wrote it |
| **Unavailable** | A reason is given. Errors are unknown, not zero |
| **Stale** | The read is older than its window. Read again before acting |
| **Truncated** | More rows exist. Read the next page or a shorter window |

Never paste log message text, customer records, passwords or tokens. Diakrin never returns message text, only codes and identifiers. If your agent does not list `app.logs.read`, diagnostics are not connected for your installation: send IT the same details.

## Diagnose and support

What IT sees and owns:

| Question | Where to look |
| --- | --- |
| Is a source connected? | `diakrin resources discover --app <app-id> --environment <environment-id>`: logs `available` with source `aws-cloudwatch-logs`, or `unavailable` with a reason. Metrics are not connected yet |
| What is read? | Only JSON log lines with an upper-case `code`, from the app's own log group (30-day retention): at most one hour and 100 rows per read. Message text is dropped, never returned |
| Which version logged it? | Each line carries the artifact digest of the task that wrote it. Match it to a version's image with `diakrin app status --version <version-id>`, which also names the operation; **Saved versions** in the console shows the latest version only |
| Which request? | The UUID `requestId` the app wrote on that line, when it writes one |
| How to recover? | Redeploy the last version that worked, then confirm the error window is clear and the app answers |
| Too many reads? | Each person gets about 6 log reads a minute (3 at once) and the installation runs at most 2 at a time, to protect your cloud's log quota. Beyond that the answer is `429 RATE_LIMITED`: wait a few seconds and retry. Every read is recorded (who, app, window, outcome) without log content |

Reads use the installation's controller role. Existing installations need the installer `update` that allows it to read app log events; until then every read is `unavailable`.

Audit is separate and mandatory. Governed actions are recorded and exported to your audit archive whether or not diagnostics or product reporting work. A diagnostics outage never turns audit off and never shows as "no errors".

## Installation health codes

The **Installation health** card in **Settings › Installations** shows the code an installation reports for a part that is degraded or down. The code names the cause, never your data. Your installation's owner fixes it; contact Diakrin support if it stays after the step below.

### SETUP_FAILED

A setup step did not finish. Open the installation's console, go to **Finish setup** and run the failed step again.

### PROVIDER_UNAVAILABLE

The installation could not reach your cloud account. Check the cloud provider's status and that the installation's role still exists.

### AUTHORITY_UNAVAILABLE

The installation could not reach the Diakrin license authority. Allow outbound HTTPS (port 443) to it, or fix the proxy setting.

### BUILD_FAILED

Recent builds are failing. Open the app's latest version for the named step and save a fixed version.

### DEPLOYMENT_FAILED

Recent deployments are failing. Redeploy the last version that worked, then check the app's deployment history.

### UNKNOWN

The part is failing for a reason it cannot name. Open the installation's console and use **Diagnose and support**.

### DATABASE_UNREACHABLE

The installation cannot reach its database. Check that the database is running and that the installation's network rules allow it.

### QUEUE_BACKLOG

Background jobs are waiting longer than normal. This clears by itself unless the jobs part is also down; if it does not, restart the jobs service.

### AUDIT_EXPORT_LAGGING

Audit records are not reaching your audit archive fast enough. Check the archive's access and free space. Audit stays mandatory while this is fixed.

### CERTIFICATE_EXPIRING

A certificate is close to expiry. Renew it before it lapses so sign-in and apps keep working.

### LICENSE_RENEWAL_FAILING

The installation could not renew its license. Check the license authority connection (see AUTHORITY_UNAVAILABLE), then contact Diakrin support before the license expires.

## Request help

Use your agreed Diakrin onboarding or support channel. Include the organization name, provider, environment, time with timezone, failing step, safe error text and whether one or all users are affected. Supply a correlation ID if the console shows one.

Never include passwords, private keys, session tokens, invitation codes, MCP tokens, customer records or screenshots that expose them.
