Troubleshooting¶
The failures people actually hit, and what to do about them.
GitHub App install lands on a "denied" page¶
You see a URL like:
You installed the App straight from its GitHub page instead of through the setup link. The App is installed on GitHub, but Forge didn't record the connection to your account. Run aegis setup and use the link it gives you. Details: Connect GitHub.
Source fetch fails on a new private repo¶
Your first deploy fails with a source/snapshot error, and the control plane couldn't clone the repo, even though the App is installed and aegis doctor looks fine.
This is a GitHub timing issue, not a Forge one. When a private repo is brand new and the App install is also new, GitHub's git endpoint can lag behind its API: the API reports the repo as accessible while git clone still returns "not found." The two run on separate caches and converge on their own.
What to do: wait a few minutes, then re-run the deploy (map deploy <sha> or push the release again). If it persists, toggle the App's repository access in GitHub → Settings → Applications → Mithran MAP Sandbox → Configure (switch to selected repos, add yours, save), which nudges GitHub to refresh.
unknown_hostname when you curl your app¶
The deploy succeeded but the URL returns unknown_hostname. The route hasn't propagated to the edge yet. Give it a few seconds and retry. If it persists past a minute, check that the deploy actually reached route_status: Ready in the Actions log.
OIDC exchange fails asking "is the repo onboarded?"¶
The deploy workflow stops at the token exchange with a message asking whether the repo is onboarded. Forge only mints a deploy token for an onboarded repo. Run map onboard <owner/repo> (or map doctor to confirm it's registered), commit the workflow if you haven't, and re-run.
MAP_INSTALLATION_REF variable is required¶
The deploy workflow needs the repo's Actions variables, which map onboard sets. If they're missing (for example, the repo was created by copying files instead of onboarding), run map onboard again, or set MAP_INSTALLATION_REF, MAP_APP_REF, MAP_TENANT_REF, and MAP_ACCOUNT_REF under Settings → Secrets and variables → Actions → Variables.
Nothing deploys when I push¶
Only release/** branches and vX.Y.Z tags deploy. A push to main or a feature branch is intentionally ignored. Cut a release branch or tag to ship. See Deploy.
Health checks fail / the app won't come up¶
The container has to listen on the port in $PORT and answer GET /health with a 200. If your app hardcodes a port or has no health route, the deploy can build but fail to become Ready. Fix the port and the health route, then redeploy.
Still stuck?¶
Grab the control plane's response from the failed Actions run. It names the stage that failed (review, build, route, runtime) and the reason. Bring that to your onboarding channel.