ContextTroubleshooting and shutdown
| Symptom | Check |
|---|---|
| Config invalid | Required .env names, origin format, exact subject and working directory |
| Cloudflare origin/tunnel error | Both processes running, correct local port/route, host awake and online |
| OAuth resource/issuer mismatch | Exact API audience/resource and canonical tenant issuer, including slash |
invalid_client or callback error | Correct predefined client, private client details and exact callback allowlist |
| 401 | Login, signature/issuer/audience/expiry and configured owner identity |
| 403 | Granted scopes; refresh/reconnect after enabling context |
| Context tool missing | Context enabled, process restarted and ChatGPT tool list refreshed |
| Link unavailable | Expired/revoked link, owner/host mismatch or changed repository root |
| Local link command fails | codex on PATH, exact stored task ID, task CWD equals Git root, repository has HEAD |
| Workflow import missing | Call get-engineering-workflow with review, build-fix, consult, prompt or project-setup |
To stop access, revoke relevant links and stop the bridge/tunnel with Ctrl+C. Disconnect the custom app in ChatGPT when retiring the instance. This guide does not install automatic startup, change DNS for unrelated services or rotate credentials for you. If credentials are exposed, rotate them at the provider; deleting a Git file does not revoke a credential.
Lessons from guided onboarding
- Use
corepack pnpm run doctor. The explicitrunselects this project's script, rather than pnpm's own command. A successful doctor check is not authentication. - Signing into the Auth0 dashboard with Google does not create the application's bridge user. Sign in through the bridge application's enabled connection using the intended owner identity. A reused session for another owner can be rejected.
- After enabling context scope, refresh the connector's actions, reconnect to authorize the changed scope, and retry in a fresh ChatGPT conversation if needed. An installed plugin or stale settings page does not prove the new tools work.
- Save only the tunnel token in the designated private file, not the entire provider installation command. Verify file existence and permissions without printing its contents. If a credential is pasted into chat, rotate it with the provider before continuing; removing the message alone does not revoke it.
- A plugin stays installed when its local server or tunnel stops. On failure, check the local health endpoint, then tunnel connectivity, then public health, then an authenticated tool call. A 502 alone does not identify the cause. This setup does not install automatic startup. Explain how to restart both processes, and verify them again after sleep, logout or reboot.
After the Auth0 trial ends
Auth0 says the Free plan activates automatically after its trial expires, with continued access to Free-plan features. Context Relay's documented single-owner configuration targets those features. Keep the existing tenant, application, API and bridge login; a new account or plugin is not the normal fallback. Auth0 trial transition.
Before expiration, inspect the tenant's enabled features and current quotas. If a trial-only feature was enabled, identify whether the bridge depends on it and replace that dependency with a supported Free-plan configuration. Do not weaken authentication or disable owner, audience or scope checks to restore access.
After transition, record actual results for:
- A fresh login as the configured bridge owner.
- An authenticated connection check.
- A permitted synthetic file read through a valid task link.
- Rejection of a revoked synthetic link.
Until performed on the Free plan, label these checks NOT RUN. A test during the trial does not establish post-trial operation. If a check fails, investigate the specific feature, quota or authentication error before changing configuration. Reinstalling a plugin does not reset provider quotas. Creating another account to restart a trial is not the recommended recovery path.
Optional GitHub build and fix workflow
ChatGPT can use its own authenticated GitHub integration to edit remote files, create branches, commit and push, open pull requests, and merge when the needed actions are available and the user and repository policies authorize them. Verify those capabilities in the current ChatGPT interface before promising a write. Context Relay supplies permitted local files and the linked task history; it does not supply GitHub write tools or bypass branch protections.
Before changing remote code, compare the local evidence with the target remote revision. Afterward, verify the remote diff and report actual tests or CI results. Reconcile the local checkout separately, preserving unpublished local work.