Troubleshooting

Authentication errors

"authentication required: run devgrid login..."

The CLI could not find valid credentials. Work through the resolution order:

1. Local development — run devgrid-cli login and verify with devgrid-cli auth status
2. CI pipeline — set DEVGRID_CLIENT_ID and DEVGRID_CLIENT_SECRET, or DEVGRID_ACCESS_TOKEN
3. Temporary override — pass --token, --username/--password, or --client-id/--client-secret on the command
4. Legacy fallback — set DEVGRID_API_KEY (deprecated; migrate to OAuth)

See Commands — Authentication for details.

"cached credentials expired; run devgrid login to authenticate again"

Your cached token from devgrid login has expired. The CLI applies a 30-second expiry buffer, so tokens near expiration are treated as expired.

Fix: Run devgrid-cli login again. There is no refresh-token flow today — you must re-authenticate when the access token expires.

If you also have DEVGRID_API_KEY set, the CLI may fall back to the API key after cached token expiry (with a deprecation warning).

"DEVGRID_API_KEY authentication is deprecated"

You are using a legacy API key. It still works as a fallback but will be removed in a future release.

Migrate to OAuth:

# Local
devgrid-cli login --username [email protected]

# CI — client credentials
export DEVGRID_CLIENT_ID=...
export DEVGRID_CLIENT_SECRET=...

Remove DEVGRID_API_KEY from your environment once OAuth is working.

SSO / password grant failures

If login fails with invalid credentials but you use SSO (Okta, Azure AD, etc.), the password grant cannot use your SSO password.

Fix: Request a dedicated service account or client credentials grant from your DevGrid administrator. Use devgrid-cli login --client-id ... --client-secret ... or set the corresponding environment variables in CI.

Wrong environment

Credentials are stored per environment (prod, dev, local). If auth status shows you are logged in but sync fails, check:

• ENV — selects config section and credential store path
• DEVGRID_ENV — selects which DevGrid API environment the SDK calls

devgrid-cli auth status --env prod
ENV=dev devgrid-cli sync

Sync and dry_run errors

"Application ... not found in DevGrid"

The appId in devgrid.yml does not match an application on the DevGrid platform.

Fix:

1. Confirm the correct short ID in the DevGrid UI
2. Update project.appId in devgrid.yml
3. Or omit appId if you only need component-level sync (see devgrid.yml — Optional appId)

"Component ... not found" or relationship warnings

Dependency and relationship targets must exist on DevGrid (or be created in the same sync). The planner may emit WARN_MISSING_TARGET for references to components that do not exist yet.

Fix: Ensure target shortId values are correct and that dependent components are defined in the same devgrid.yml or already exist remotely.

Sync fails after config changes

Run lint and dry run before sync:

devgrid-cli lint
devgrid-cli dry_run

Review devgrid_dry_run_plan.json (or stdout if configuration.dryRunOutput: stdout) before applying.

devgrid.yml validation errors

"additional properties ... not allowed"

The schema is strict — only documented fields are permitted. Common causes:

See the devgrid.yml field reference for the complete list of valid fields.

"required property ... is missing"

Every component needs name and shortId. The top-level project object is required.

project:
  components:
    - name: my-service    # required
      shortId: svc-001    # required

shortId type errors

shortId, appId, and relationship to accept strings or integers. Ensure YAML quoting is correct for string IDs that look numeric.

Installation issues

macOS: "cannot be opened because the developer cannot be verified"

The downloaded binary is quarantined by Gatekeeper.

Fix:

xattr -d com.apple.quarantine ./devgrid-cli

See Setup — macOS Gatekeeper.

"Permission denied" on Linux or macOS

The binary is not executable.

Fix:

chmod +x devgrid-cli

See Setup — macOS / Linux install.

Command not found

The CLI directory is not on your PATH.

Fix: Use the full path to the binary, or add its directory to PATH:

export PATH="$HOME/bin:$PATH"

Wrong architecture binary

Download the archive matching your OS and CPU:

• Apple Silicon Mac → devgrid-latest-darwin-arm64.tar.gz
• Intel Mac → devgrid-latest-darwin-x64.tar.gz
• Linux ARM → devgrid-latest-linux-arm64.tar.gz

See Setup — Download.

Logging

Increase verbosity to diagnose API or sync issues:

export DEVGRID_LOG_LEVEL=DEBUG
devgrid-cli sync

Valid levels: DEBUG, INFO, WARN, ERROR.

Get help

If you are still stuck:

• Email: [email protected]
• Support portal: support.devgrid.io
• Documentation: use the discussion feature on the relevant docs page

Include the command you ran, relevant environment variable names (not values), and the full error message.