Troubleshooting

Missing token

Error:

Error: UIGRAPH_TOKEN environment variable is required

Fix:

• Export UIGRAPH_TOKEN locally.
• Set UIGRAPH_TOKEN in CI secrets for pipeline runs.

Missing gateway URL

Error:

Error: gateway URL is required (set --enterprise, --api-url or UIGRAPH_GATEWAY_URL environment variable)

Fix, depending on where you sync to:

• Hosted UIGraph: add --enterprise to the command.
• Self-hosted UIGraph: export UIGRAPH_GATEWAY_URL, or pass --api-url.

A related error means --enterprise was given a value it does not accept:

Error: --enterprise accepts no value or =DEV, got "dev"

The only accepted value is DEV, in capitals, as in --enterprise=DEV. Pass the flag on its own for the production environment.

Missing repository provider

Error:

Validation error: service.repository.provider is required

Fix:

service:
  repository:
    provider: github
    url: https://github.com/org/repo

Allowed values: github, gitlab, bitbucket.

Referenced file not found

Examples:

apis[0].path file does not exist: ./openapi.yaml
architectureDiagrams[0].contextPath file does not exist: ./context.json
databases[0].schemaPath file does not exist: ./schema.sql

Fix:

• Verify file paths in .uigraph.yaml.
• Ensure paths are correct for the current working directory in CI.
• Commit the files that are referenced.

API-linked test case does not resolve

If an API test case is not linking as expected:

• confirm apiGroupName matches the synced API group name
• confirm operationId exists in the OpenAPI file
• re-run uigraph-cli sync --dry-run after updating the spec or config

Unsupported type value

Examples:

apis[0].type must be one of: openapi, graphql, grpc
testPacks[0].type must be one of: smoke, regression, manual
testPacks[0].testCases[0].type must be one of: api, manual
databases[0].dialect must be one of: postgres, mysql, sqlite, dynamodb, mongodb, other

Fix:

• Use one of the accepted enum values exactly.

Sync stops with a 403 partway through

A token missing a scope gets a 403 on the first request that needs it, and the CLI exits with code 2 at that step. Earlier steps are already applied; later ones are not.

Step that fails	Missing scope
Service, APIs, dependencies, diagrams, databases, queries, test packs, docs	services:write
Cost tags	billing:write
Timeline events, uigraph-cli release	timeline:write
Maps, frames, focal points	maps:write
ML projects	mlstudio:write

Fix: grant the missing scope on the service-account token, then re-run. The sync is idempotent, so re-running from the start is safe.

Screenshot path is rejected

Examples:

testPacks[0].testCases[1].screenshots[0] file does not exist: ./screens/checkout.png
testPacks[0].testCases[1].screenshots[0] must be a file, not a directory: ./screens
testPacks[0].testCases[1].screenshots[0] must be an image (.png, .jpg, .jpeg, .gif, .webp, .svg): ./screens/checkout.pdf

Fix:

• Commit the image and check the path is relative to the working directory the CLI runs in.
• Point at the file, not the folder that holds it — there is no directory expansion.
• Convert to one of the accepted extensions. The check is on the extension, not the file's contents.

Timeline is empty after a sync

The scan reports what it found:

🕓 Syncing 0 timeline events...

Zero events with a timeline block configured almost always means the globs matched nothing. Common causes:

• A ** pattern. Recursive globs are not supported. docs/**/*.md matches nothing; list each directory as its own single-level pattern (docs/adr/*.md, docs/adr/2026/*.md).
• Wrong working directory. Patterns resolve from where the CLI runs, not from the location of .uigraph.yaml.
• Extension mismatch. *.md does not match .markdown or .mdx.

Changelog produces no release events

The parser only recognises ## headings that begin with a digit, optionally bracketed and optionally prefixed with v:

## [1.4.0] - 2026-07-14
## 1.4.0 - 2026-07-14
## [v1.4.0]

Headings like ## Release 1.4.0, ## Version 1.4.0, or ## [Unreleased] are skipped — the first two because they do not start with a digit, the last because it has no version to key the event on. Reformat the headings, or drop timeline.releases.changelogPath and record releases with uigraph-cli release.

Decision or incident file fails the scan

docs/adr/0007-queueing.md: no title in front matter and no '# ' heading
docs/adr/0007-queueing.md: decision status "draft" must be one of: proposed, accepted, superseded, deprecated
docs/adr/0007-queueing.md: date "14-07-2026" is not YYYY-MM-DD or RFC3339

Fix:

• Give the file a # heading or a front-matter title.
• Use one of the four status values, or drop the Status section.
• Write dates as YYYY-MM-DD or full RFC 3339. A malformed date is an error, not a fall-through to the commit date.

uigraph-cli release cannot resolve the version

Error: no --version given and HEAD is not tagged; pass --version explicitly

Causes and fixes:

• Shallow clone. CI checkouts default to a shallow fetch with no tags. Set fetch-depth: 0 (GitHub Actions) or GIT_DEPTH: 0 (GitLab).
• The job did not run on a tag. Gate it on startsWith(github.ref, 'refs/tags/') or $CI_COMMIT_TAG.
• Deliberately releasing an untagged commit. Pass --version yourself.

Empty release notes usually have the same root cause: without full history there is no previous tag, so there is no commit range to fall back to.

Cost tags disappeared from a service

costTags is declarative. When the section is present in .uigraph.yaml, the config owns the full set and the next sync deletes any rule that is not listed — including rules added by hand in the UI. costTags: [] clears them all.

Fix: either add the rules to .uigraph.yaml, or remove the costTags section entirely so the CLI stops managing them.

Fast debug workflow

1. Run uigraph-cli sync --dry-run.
2. Fix first validation error.
3. Re-run dry-run until it is clean.
4. Run normal sync in CI.

When a sync is slow or a request keeps failing, add --verbose. It logs every MLflow and gateway request with how long it took, which shows you the call responsible.

Missing git metadata

If the CLI cannot capture git metadata, sync can still continue.

Typical causes:

• running outside a git repository
• running in a shallow or restricted CI environment
• missing git binary in the runtime image