Troubleshooting Guide

Last updated: July 22, 2026

First checks

Before changing configuration or retrying a destructive action:

1. Confirm you are using the correct application URL and organization.
2. Note the approximate time, page, visible message, and request ID if shown.
3. Confirm your session is signed in and, for privileged work, at AAL2 MFA.
4. Refresh once. Do not repeatedly submit billing, support, export, or artifact actions.
5. Check the service status with /health. Deployment operators should also inspect hosting and provider logs.

Never send support your password, MFA code, session token, database URL, API key, webhook secret, CUI, PHI, payment-card data, or raw customer production content.

Sign-in and MFA

Symptom	Likely cause	Resolution
Confirmation link returns to the sign-in page	Link expired, was already used, or the redirect origin is not allowed	Request a new confirmation email. Operators should verify the Auth site URL and redirect allowlist.
Password-reset email does not arrive	Address mismatch, spam filtering, SMTP/provider issue, or rate limiting	Wait several minutes, check spam, then request one new email. Contact support if it still does not arrive.
"Your session expired"	Access token expired or local session was cleared	Sign in again. Do not reuse a copied bearer token.
HTTP 401 on an application action	Missing, expired, or invalid session	Sign out, close stale tabs, sign in again, and retry once. Operators should verify JWKS, issuer, and audience configuration.
HTTP 403 after sign-in	Wrong organization, insufficient role, missing entitlement, or AAL2 required	Confirm the workspace, role, plan, and MFA state. Cross-tenant denial is expected behavior.
Owner/Admin cannot access tenant data	Session is AAL1	Open Account -> Multi-factor authentication, enroll or verify TOTP, and return with an AAL2 session.
TOTP code is rejected	Device time drift, wrong account, expired code, or factor not enrolled	Enable automatic time on the authenticator device, wait for the next code, and verify the account label. Contact support for recovery if the factor is lost.

System registration and questionnaire

Symptom	Resolution
Create registry record remains disabled	Complete every required field, choose at least one data class, select hosting and boundary status, and enter at least 200 purpose characters.
"Regulated-data-like content detected"	Remove CUI, PHI, customer records, secrets, source code, prompt/output content, and other raw payloads. Replace them with a classification, approved reference, owner, date, or control description.
"None sensitive" is removed when another class is selected	This is expected. "None sensitive" cannot be combined with PII, PHI, CUI, FCI, or another sensitive class.
A framework question is missing	Confirm the applicable pack is selected for the system and the subscription includes that pack. Refresh entitlements after any billing change.
A saved answer appears only attested	Attach approved evidence to the specific saved answer. An assertion without linked evidence remains attested by design.

Evidence upload

Supported files

PDF, CSV, XLS, XLSX, DOC, DOCX, PNG, JPG, and JPEG are supported up to 25 MB. The extension must match the file's MIME type, and the filename cannot contain path separators.

Symptom	Likely cause	Resolution
"No saved answers yet"	Evidence must support an existing answer	Open an AI system, save at least one mapped answer, then return to Evidence upload.
"Unsupported evidence type"	Extension/MIME mismatch or unsupported format	Export the file to a supported format. Do not merely rename the extension.
File exceeds 25 MB	Object and scanner limit	Create a smaller, approved extract or split the evidence outside CompliAffirmAI. Do not remove required context or integrity information.
Private storage returns HTTP 4xx	Signed URL expired, bucket policy/CORS issue, disallowed MIME type, or incorrect request headers	Request a new upload intent. Operators should confirm bucket privacy, allowed MIME types, CORS, clock accuracy, endpoint, and credentials.
Scan remains pending	Scanner or sealing process has not completed	Wait briefly and refresh. Do not rely on or export the file until it reports Scan passed.
Scan failed	Provider error, timeout, hash mismatch, size mismatch, or sealing failure	Do not keep retrying the same request. Confirm the local file is unchanged, then retry once with a new upload intent. Operators should inspect scanner and storage logs.
File quarantined	Malware or restricted active content detected	Do not download, repackage, or bypass the finding. Follow your incident procedure and contact the security team.
Evidence is missing from another workspace	Tenant isolation	Confirm the organization. Evidence never moves between organizations automatically.

Governance readiness and TRAIGA Cure Binder

Symptom	Resolution
Readiness shows Not assessed	Save an answer for the mapped question.
Readiness shows Attested	The answer exists but no qualifying evidence is linked. Attach evidence if appropriate.
Readiness shows Partially evidenced	Some supporting elements exist, but the mapping is incomplete. Open the item and review the listed controls and evidence.
Readiness shows Gap	The selected answer does not meet the deterministic acceptance rule or required support is missing. Assign remediation and record the corrected state when complete.
Review/test form will not save	Required scope, method, findings, date, or discovery summary is missing or too short. Complete the visible required fields with metadata-only content.
Cure Binder is unavailable	TRAIGA entitlement, a selected system, or provider storage may be missing
Binder says counsel_review_required	Expected legal boundary

Artifact and ledger issues

Symptom	Resolution
Artifact generation returns 403	Confirm plan entitlement, system access, role, and MFA.
Artifact generation returns 503	Database or private storage is unavailable, or a multi-format write failed
Download returns 404	Wrong organization, artifact ID, or removed record
Download fails SHA-256 verification	Stored object does not match its manifest
Ledger verification reports a divergence	An event is missing, reordered, or altered
Ledger verifies cleanly but content is disputed	Integrity is not truth

Billing and entitlements

Symptom	Resolution
Checkout button is unavailable	Initial Checkout requires a confirmed Owner and a valid plan selection; Solo also requires a framework choice
Payment completed but access is unchanged	Signed webhook and entitlement synchronization may still be processing
Billing Portal is denied	Portal access requires Owner/Admin and AAL2
Plan is active but an artifact is unavailable	Pack or system-limit entitlement mismatch
Partner plan cannot be purchased in self-service Checkout	Expected behavior

Support, export, and deletion requests

• If a support request appears to fail, check Support history before submitting it again. Requests use idempotency protections.
• Workspace exports are available only to Owner/Admin sessions and use no-store download headers.
• Deletion requests are queued for identity verification and retention review. Ledger and legal-retention obligations may prevent immediate physical deletion of every record.
• Never include sensitive payloads in the request description.

HTTP and API reference

Status	Meaning in this platform	Recommended action
400	Invalid request state	Recheck the visible form and selected workflow.
401	Authentication missing or invalid	Sign in again.
403	Organization, role, MFA, or entitlement denied	Confirm workspace, role, AAL2, and plan. Do not attempt to bypass.
404	Record is absent in the authorized organization	Open the record from the current workspace navigation.
409	State or idempotency conflict	Refresh and inspect the current record before retrying.
422	Validation or metadata-only rule failed	Correct the named field, type, size, or content.
429	Rate limit reached	Honor Retry-After; stop automated retries.
503	Configured database/provider unavailable or fail-closed	Operators should inspect the named provider and runtime logs.

Deployment-operator diagnostics

Run read-only checks before changing production:

curl.exe -sS https://your-domain.example/health
vercel inspect <deployment-url>
pnpm smoke:production-logs -- --since 30m --allow-empty

Common deployment causes:

• build succeeded but the wrong Git SHA was promoted;
• a secret exists only in Preview, not Production;
• a browser value contains a copied BOM or zero-width character;
• Auth issuer/audience/redirect URLs do not match the production origin;
• the database URL uses an admin/bypass role instead of the application role;
• the private bucket lacks an accepted MIME type such as application/zip;
• Stripe Product, Price, Portal, or webhook IDs belong to another application; or
• the custom domain still points to a previous deployment.

After a repair, rerun the canonical gate, deploy the exact tested commit, exercise the affected golden path, and inspect logs again.

Contacting support

Email support@compliaffirmai.app with:

• organization/workspace name;
• page and action;
• approximate time and time zone;
• visible error and HTTP status;
• request ID, artifact ID, system ID, or evidence ID if shown; and
• whether the issue is reproducible.

For a suspected vulnerability, cross-tenant exposure, malware bypass, integrity failure, or credential disclosure, stop normal troubleshooting and email security@compliaffirmai.app.

Back to Client Documentation