> ## Documentation Index
> Fetch the complete documentation index at: https://nextjs-egg.nyxel.my.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix common problems with startup, builds, private repos, and dependencies.

<AccordionGroup>
  <Accordion title="Server stays at 'Starting...' forever">
    **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.
  </Accordion>

  <Accordion title="Build fails in production mode">
    **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.
  </Accordion>

  <Accordion title="Private repo cloning fails">
    **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.
  </Accordion>

  <Accordion title="npm ci fails">
    **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:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="Server fails to start with 'No package.json found'">
    **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.
  </Accordion>

  <Accordion title="Port conflict or app not accessible">
    **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.
  </Accordion>

  <Accordion title="pnpm or yarn not found">
    **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.
  </Accordion>
</AccordionGroup>

<Tip>
  If you encounter a bug or unexpected behavior that isn't covered here, open an issue at [https://github.com/Synxx12/nextjs-egg](https://github.com/Synxx12/nextjs-egg).
</Tip>