Troubleshooting
The setup checklist is on /admin/login and on Admin → Settings → GitHub. The same checks come from GET /api/_pluto/github/setup/status. The checks show ok or missing. They never show a secret.
When the sign-in works, the status route answers { ready: true } and nothing more.
Setup checks
| Check | Cause | Fix |
|---|---|---|
repo | Pluto cannot find the repository. | Set PLUTO_GITHUB_REPO to owner/name. See Reference. |
sessionPassword | NUXT_PLUTO_GITHUB_SESSION_PASSWORD is not set, or it has fewer than 32 characters. | Set a random value of 32 characters or more. Run openssl rand -base64 32. |
appId | NUXT_PLUTO_GITHUB_APP_ID is not set. | Paste the env block from Quickstart, or set the App ID. |
clientId | NUXT_PLUTO_GITHUB_CLIENT_ID is not set. | Set the Client ID of the App. |
clientSecret | NUXT_PLUTO_GITHUB_CLIENT_SECRET is not set. | Set the client secret of the App. If you lost it, generate a new one on the App page on GitHub. |
privateKey | The private key is not set, or Pluto cannot parse it. | Set NUXT_PLUTO_GITHUB_PRIVATE_KEY. Use one of the key formats. |
installation | The App is not installed on the repository. Pluto checks this only when the App ID and the key are fine. | Install the App on the content repository. Use the Install the App link. |
After you change a variable, restart the dev server or redeploy the site.
Sign-in errors
The sign-in redirects to /admin/login?error=<code>.
| Code | Cause | Fix |
|---|---|---|
state | The state value does not match. The sign-in cookie expired (10 minutes), or the browser blocked it. | Start the sign-in again. Use the same URL from start to end. |
not_installed | The user or the App cannot see the repository. | Install the App on the repository. Check that the user has access to the repository. |
forbidden | The user has no admin, maintain, or push permission. Or the login is not in NUXT_PLUTO_GITHUB_ALLOWED_USERS. | Give the user push access. Or add the login to the allow list. |
denied | The user canceled at GitHub. | Sign in again and select Authorize. |
github | Any other failure. The callback URL may be missing in the App, or a value may be wrong. | Check the setup checks. Check the callback URL. See below. |
Callback URLs
The GitHub App must list the callback URL of each site URL that you use to sign in. The path is the same for all of them: /api/_pluto/auth/github/callback.
| Environment | Callback URL |
|---|---|
| Local | http://localhost:3000/api/_pluto/auth/github/callback |
| Production | https://<your-site>/api/_pluto/auth/github/callback |
| Vercel preview | https://<preview-url>/api/_pluto/auth/github/callback |
The Create the GitHub App button adds the production URL and the local URL for you.
A Vercel preview has a new URL for each deployment. GitHub allows at most 10 callback URLs for one App. Do not add each preview URL. Sign in on the production URL.
To add a URL by hand, open the App on GitHub. Open Settings, Developer settings, GitHub Apps, select your App, and edit Callback URL.
The setup page answers 404
The Create the GitHub App routes (/api/_pluto/github/setup/start and /api/_pluto/github/setup/callback) work in two cases:
- You run the dev server on your machine.
- The sign-in is not configured yet.
When the sign-in works, a production site answers 404 on these routes. To create a new App, remove the old values from the environment first. Then redeploy.
The App page on GitHub is at https://github.com/settings/apps.