Reference

Troubleshooting and help

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

Deployment
BYOC and self-hosted

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

SSO will not start BYOC only

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.

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 BYOC only

SymptomFirst check
Audience or destination mismatchExact SP Entity ID and ACS URL from the setup packet
Missing emailSend the work email as email, or agree the exact attribute mapping
Invalid signatureCurrent certificate, signing algorithm and registered metadata
User changes on each sign-inStable NameID; avoid transient identifiers
Return to the wrong siteCorrect environment and console return URL
Worked before certificate renewalUpdated 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.

My invitation does not work BYOC only

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.

Builder errors on a self-hosted installation Self-hosted only

ErrorWhat it meansNext step
APP_CREATE_BLOCKEDThe 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_DIAKRINThe 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_REQUIREDNo 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_EXHAUSTEDThis month's approved budget is used up. Nothing was built or deployed.Ask the owner to raise the limit, then retry.
VERSION_NOT_LATESTOnly your latest saved version can be published.Save your change as a new version, then publish it.
ROLLBACK_PLAN_REFRESH_REQUIREDThe earlier version's plan or approval has expired.Ask the owner to approve a fresh plan, then roll back again.
ROLLBACK_SCHEMA_UNKNOWNRollback 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 saysWhat it means
AvailableEach 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
UnavailableA reason is given. Errors are unknown, not zero
StaleThe read is older than its window. Read again before acting
TruncatedMore 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 Self-hosted only

What IT sees and owns:

QuestionWhere 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 BYOC only

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.