Skip to main content

Troubleshooting

This page covers the most common issues encountered with The One Code and their resolution steps.

1. "State token expired" error during GitHub connection​

Symptom: After installing the GitHub App on GitHub, you're redirected back to The One Code with an error page that says the state has expired or is invalid.

Cause: The connection state token has a 10-minute TTL. If you spent more than 10 minutes on the GitHub installation page (perhaps reviewing which repositories to grant access to), the state expired before GitHub redirected back.

Resolution:

  1. Go back to The One Code
  2. Navigate to Organizations → Connect Organization
  3. Start the connection flow again
  4. Complete the GitHub App installation promptly (under 10 minutes)

2. Repositories not appearing after GitHub App installation​

Symptom: You completed the GitHub App installation and were redirected back, but the organization shows 0 repositories or is missing expected repos.

Cause: Repository enumeration happens in the callback. A GitHub API timeout or partial response can result in incomplete enumeration.

Resolution:

  1. Navigate to Organizations
  2. Find the newly connected org
  3. Click Sync Repositories
  4. The One Code will query the GitHub API fresh and add any missing repositories

If the sync shows 0 repos and the org has repositories, verify that the GitHub App installation granted access to the repositories (not just the organization without repo access). From GitHub Settings → Third-party Access, check the installation and confirm repository access is not set to "No repositories."

3. Backup jobs stuck in "pending" indefinitely​

Symptom: Backup jobs show status pending and never transition to running or completed.

Cause: The backup worker fleet (Azure Service Bus triggered workers on the Consumption plan) may not have processed the message. This can happen if:

  • The theonecode-workers Function App is cold-starting
  • The Service Bus connection string is invalid
  • The workers Function App is not deployed

Resolution:

  1. Check the backup job status by navigating to the repo and clicking View Backup History
  2. If jobs are pending for more than 15 minutes, check the Azure portal for theonecode-workers Function App errors
  3. Try triggering a manual backup — this queues a new job at high priority (priority 8)
  4. If the issue persists, the SERVICE_BUS_CONNECTION_STRING environment variable on the workers Function App may be incorrect

4. AI documentation generation fails or returns empty documents​

Symptom: You triggered documentation generation but the job completed with 0 documents, or documents were generated with very sparse content.

Cause: Several possible causes:

  • No application profile exists for the repository (analysis hasn't run yet)
  • The GitHub App installation doesn't have content access to the repository
  • The AI Gateway is unavailable or rate-limited
  • The repository has no source files (empty repo or only binary files)

Resolution:

  1. Verify an application profile exists: go to the repo detail page and check the Analysis section. If the profile shows "unknown" for app type with empty tech stack, run Analyze Portfolio first.
  2. Verify GitHub App access: navigate to GitHub Settings → Apps → Installed GitHub Apps → The One Code, and confirm the repo is listed under repository access.
  3. If the AI Gateway is the issue, wait a few minutes and retry — AI generation uses retry logic but can fail under heavy load.
  4. For empty repositories, documentation cannot be generated until source files are added.

5. Secret scan shows "no results" for a repository you know has secrets​

Symptom: You run a secret scan on a repository that you know contains hardcoded credentials, but the scan returns no findings.

Cause: The secret scanner reads file contents via the GitHub API. If the credentials are:

  • In binary files (the scanner reads text files only)
  • In files with non-standard extensions not included in the scan
  • Only in git history (not the current HEAD of the default branch) — the scanner does look at history, but may not have traversed all branches

Resolution:

  1. Check that the files you expect to be scanned have standard text extensions (.env, .js, .ts, .py, .json, .yaml, .config, etc.)
  2. Re-run the scan — the first scan after connecting may not have traversed the full git history
  3. If the secret was committed and then removed (but is in history), re-running with a full history scan flag should surface it

6. Access audit returns "Organization not found" or empty results​

Symptom: Triggering an access audit for an org returns an error, or the audit completes but shows 0 members.

Cause: The GitHub App must have Organization members read permission for the installation. If the app was installed without this permission, or the org has restricted third-party access, the member API will return empty results.

Resolution:

  1. Go to GitHub Settings → Developer Settings → GitHub Apps → The One Code → Permissions
  2. Verify "Organization members" is set to "Read"
  3. If permission was recently added, you may need to re-install (update) the GitHub App on the org
  4. For organizations with SSO (SAML), members may need to authorize the GitHub App — look for an authorization prompt in GitHub

7. Compliance report shows all controls as "Not Applicable"​

Symptom: You generate a SOC 2 or ISO 27001 report but all or most controls show "Not Applicable" rather than Pass or Fail.

Cause: Compliance evidence is collected from the data already in your tenant. If no access audits, secret scans, or backup verifications have been run, there's no evidence to map to controls.

Resolution:

  1. Run an access audit for each connected org: Organizations → [Org] → Run Access Audit
  2. Run a secret scan for each org: Secret Scan → Scan All
  3. Verify that backup verification is enabled and has passed for at least one backup
  4. Re-generate the compliance report after collecting evidence

8. "GitHub App installation required" error when generating docs​

Symptom: When triggering documentation generation, you receive the error "GitHub App installation required for doc generation."

Cause: Documentation generation reads file contents from GitHub using the GitHub App installation token. This error means the organization connected to the repository is using OAuth (GitLab or Azure DevOps) rather than the GitHub App, or the GitHub App has been uninstalled.

Resolution:

  • For GitHub orgs: verify the GitHub App is still installed. Navigate to the org detail page — if it shows auth_type: oauth instead of github_app, the App connection was lost. Reconnect via the GitHub connect flow.
  • For GitLab and Azure DevOps repos: documentation generation currently requires GitHub App access. This is a known limitation — GitLab and Azure DevOps documentation generation is planned for a future release.

9. Portfolio shows "unknown" app type for all repositories​

Symptom: After connecting an org and waiting for backups, the portfolio shows all repos with app type "unknown" and empty tech stacks.

Cause: Application profile analysis (the AI step that detects app type, tech stack, and frameworks) runs separately from backup. Analysis is not triggered automatically on first connect.

Resolution:

  1. Navigate to Portfolio
  2. Click Analyze All (or navigate to Organizations → [Org] → Analyze All Repos)
  3. Wait 2–5 minutes for analysis to complete per repository
  4. Profiles will update with detected app types, tech stacks, and health scores

10. Login fails with "session not found" after clicking through from Hub​

Symptom: You click the Code product in the Hub waffle menu but are shown a "session not found" or authentication error page.

Cause: The Hub SSO handoff uses a short-lived token (70-second TTL) to validate the Hub session and create a local Code session. If the redirect took longer than 70 seconds, or if the PORTAL_SSO_SECRET environment variable on theonecode-api doesn't match Hub's secret, the handoff fails.

Resolution:

  1. Try navigating directly to app.theonecode.app — if you're already logged into Hub, the SSO handoff will retry
  2. If the error persists, verify that your Hub account has Code product access enabled: in Hub, go to Settings → Users → [Your Name] → Products and confirm Code is enabled
  3. If SSO is consistently failing across all users, the PORTAL_SSO_SECRET environment variable may be mismatched between Hub and The One Code — contact support

When to Contact Support​

Contact support at [email protected] or open a ticket in PSA if:

  • Backup jobs fail with an error message containing "storage" or "blob" — indicates a storage account misconfiguration
  • The entire application is returning 500 errors — indicates a Function App deployment issue
  • You see "Service Unavailable" (503) responses — the Function App may need to be restarted
  • An access audit crashes with no error message — likely a GitHub API scope issue requiring a permission re-review
  • AI documentation has been "generating" for more than 15 minutes — the AI job may be stuck

For most operational issues, the steps above resolve the problem without escalation.