Skip to main content
Cause: The panel marks a server as online only after it detects one of the following strings in the process stdout:
  • ready on
  • started server on
  • Local: http://
  • Compiled successfully
  • listening on
  • ▲ Next.js
If Next.js starts successfully but none of these strings appear in stdout, the panel never transitions the server out of the “Starting…” state.Fix: Check your server logs in the panel console. Common causes:
  • You are wrapping next start or next dev in a custom script that redirects or discards stdout. Remove any output suppression and let Next.js write directly to stdout.
  • Your app has a build error that prevents Next.js from reaching the ready state. Look for a next build failure earlier in the log output.
  • If you are using a custom server (e.g. server.js), make sure it still starts Next.js and that the ready message reaches stdout unchanged.
Do not pipe next start through tools like quiet or redirect stdout to /dev/null. The panel’s startup detection depends on reading that output directly.
Cause: next build failed because one or more environment variables required at build time are missing. Next.js bakes certain env vars (those prefixed with NEXT_PUBLIC_, and any others your code accesses at build time) into the compiled output. If they are absent during the build, the build will fail or produce a broken app.Fix:
  1. Create a .env file locally with all required build-time variables and their correct values.
  2. Rename the file to .env.pterodactyl.
  3. Upload it to /home/container/ using the panel’s File Manager.
  4. Restart your server. The egg copies .env.pterodactyl to .env before running next build, so all variables will be available during the build.
Check the panel console for the full next build error output — it usually identifies which variable or module caused the failure.
Cause: One of the following:
  • Your personal access token has expired or was revoked.
  • The token does not have the required scope: repo for GitHub or read_repository for GitLab.
  • Credentials are embedded directly in GIT_URL (e.g. https://user:token@github.com/...), which conflicts with the egg’s own credential injection.
Fix:
  1. Generate a new personal access token:
    • GitHub: Go to Settings → Developer settings → Personal access tokens (classic) and create a token with the repo scope.
    • GitLab: Go to User Settings → Access Tokens and create a token with the read_repository scope.
  2. Set GIT_URL to the plain HTTPS URL of your repository — no username or token embedded: 
    https://github.com/your-username/your-repo
  3. Set USERNAME to your GitHub or GitLab username.
  4. Set ACCESS_TOKEN to the token you just created.
The egg constructs the authenticated URL internally. Embedding credentials in GIT_URL will cause the URL to be malformed after the egg applies its own injection.
Cause: npm ci requires package-lock.json to be in exact sync with package.json. If you have added, removed, or updated packages in package.json without regenerating the lockfile, npm ci will fail with a dependency mismatch error.Fix — option 1 (recommended): Regenerate your lockfile locally:
npm install
git add package-lock.json
git commit -m "chore: update lockfile"
git push
On the next server start (with AUTO_UPDATE=1), the egg will pull the updated lockfile and npm ci will succeed.Fix — option 2: Delete package-lock.json from the container via the File Manager. Without a lockfile, the egg falls back to npm install, which resolves dependencies fresh and generates a new lockfile.Fix — option 3: Set PACKAGE_MANAGER to pnpm or yarn and commit the corresponding lockfile instead. Both pnpm and yarn also fall back gracefully from --frozen-lockfile to a regular install if the lockfile is absent.
Cause: GIT_URL is empty and no project files exist in the container. The egg has no repository to clone and cannot find a package.json to work with, so it exits immediately with:
[EGG] ERROR: No package.json found and GIT_URL is empty.
[EGG] Please upload your project files via File Manager or set GIT_URL.
Fix — option 1: Set GIT_URL to your repository’s HTTPS URL in the server’s Startup tab and restart. The egg will clone the repository automatically.Fix — option 2: Upload your project files manually:
  1. Build or prepare your Next.js project locally.
  2. Open the panel File Manager for your server.
  3. Upload your project files to /home/container/, making sure package.json is present at the root.
  4. Restart the server. With GIT_URL empty and package.json present, the egg will skip the git step and proceed with install, build, and start.
Cause: Your Next.js app or a custom server file is hardcoding a port number instead of using the one the egg provides. The egg always passes the panel-assigned port as $SERVER_PORT to next start -p $SERVER_PORT or next dev -p $SERVER_PORT. If your app also binds to a different port inside next.config.js or a custom server.js, the two will conflict or the panel-assigned port will be left unbound and unreachable.Fix:
  • Do not hardcode a port in next.config.js, server.js, or any other file.
  • If you use a custom server, make sure it reads the port from the PORT environment variable or another mechanism — but note the egg uses SERVER_PORT, not PORT. The simplest approach is to let the egg call next start directly (the default behavior) rather than using a custom server.
  • Do not override the SERVER_PORT variable in the panel — it is injected automatically by the panel based on the port allocation for your server.
After fixing the configuration, restart your server. Your app will be accessible on the port shown in the panel’s network settings.
Cause: The Docker image used by the egg ships with npm only. pnpm and yarn are not pre-installed. When the egg detects that pnpm or yarn is needed (either by lockfile detection or because you set PACKAGE_MANAGER explicitly), it installs the package manager globally via npm before proceeding. This install happens at startup, not during the image build.Fix: This is expected behavior — no action is required. On the first start where pnpm or yarn is needed, there will be a brief delay (usually 10–30 seconds) while the package manager is downloaded and installed. On subsequent starts it will already be present and the delay will not occur.If the install fails, check that your server has outbound internet access and that npm’s registry is reachable from within the container. You can also try switching PACKAGE_MANAGER back to npm if you do not have a pnpm or yarn lockfile committed.
If you encounter a bug or unexpected behavior that isn’t covered here, open an issue at https://github.com/Synxx12/nextjs-egg.