> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deploxy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Guide

> Find solutions to common issues and problems encountered during deployment and runtime of your MCP server.

This guide covers common issues you might encounter when using Deploxy and provides step-by-step solutions.

## Pre-Deployment Checklist

Before running `npx @deploxy/cli deploy`, ensure your project is ready for publishing. Deploxy deploys your project as-is, so it must be fully built and configured correctly.

1. **Project is Built**: You must run your build command (e.g., `npm run build` or `tsc`) to compile your code **before** deploying. Deploxy does **not** run your build script. It only installs production dependencies (e.g., `npm install --production`) on the server.
2. **`package.json` is Correct**:
   * The `name` and `version` are set for publishing to NPM.
   * The `main` field points to the entry file of your **built** code (e.g., `dist/index.js`).
   * The `files` array includes your build output directory (e.g., `["dist"]`). This ensures your compiled code is included in the deployment.
3. **Dependencies are Production-Ready**: Your `dependencies` should contain only what's needed to run your server in production. Build tools like `typescript`, `eslint`, and bundlers should be in `devDependencies`.

<Tip>
  Think of `npx @deploxy/cli deploy` as a direct replacement for `npm publish`. Just as you would build your project before publishing to NPM, you must build your project before deploying with Deploxy.
</Tip>

## Deployment Issues

These issues occur when running the `npx @deploxy/cli deploy` command.

### Deployment Fails with "Unauthorized"

**Symptom:** The deploy command fails with a `401 Unauthorized` error.

**Solution:**

1. **Verify `authToken`:** Ensure the `authToken` in your `.deploxy.json` is correct and has not expired.
2. **Regenerate Token:** Go to the [Tokens page](https://deploxy.com/account/settings/tokens) on your dashboard, generate a new token, and update your configuration file.
3. **Check for Typos:** Make sure there are no extra spaces or characters in the token string.

### Deployment Fails Due to Missing Files or Entry Point Error

**Symptom:** The deployment fails, and the logs on the Deploxy dashboard indicate that the entry point specified in `package.json` could not be found, or other necessary files are missing.

**Solution:**
This almost always means your project was not built before deployment, or your `package.json` is not configured to include the built files.

1. **Build Your Project:** Run your project's build script locally (e.g., `npm run build`).
2. **Check `package.json` `main` field:** The `main` field must point to the main file of your compiled output, not your source TypeScript or JavaScript file.
   ```json package.json theme={null}
   {
     "main": "dist/index.js" 
   }
   ```
3. **Check `package.json` `files` field:** The `files` array tells Deploxy which files and folders to include in the deployment. It **must** include your build output directory.
   ```json package.json theme={null}
   {
     "files": ["dist"]
   }
   ```

### Deployment Package Too Large

**Symptom:** The deployment fails with a message related to the package size limit.

**Solution:**
The total unzipped size of your project, including `node_modules`, must be **under 250MB**.

1. **Check `devDependencies`:** Ensure that build-time tools (like `typescript`, `@types/*`, `eslint`, bundlers) are in `devDependencies` and not `dependencies`. Only `dependencies` are installed on the server.
2. **Analyze Dependencies:** Use a tool like `npm-why` or `yarn why` to find and remove unnecessary packages from your `dependencies`.
3. **Prune `devDependencies` locally:** Before deploying, you can simulate a production install to see the true size of your `node_modules`. Create a temporary directory, copy your `package.json` and `package-lock.json` into it, and run `npm install --production`.

### NPM Publishing Fails

**Symptom:** The deployment process succeeds until the "Publishing to NPM..." step.

**Solution:**

1. **Check NPM Authentication:** Ensure your `.npmrc` file is present in the project root and contains a valid NPM token with publish permissions. The `NPM_TOKEN` environment variable must be available in your shell.
2. **Check Package Version:** NPM requires a unique version for every publish. Before deploying, you must increment the `version` in your `package.json`.
3. **Check Package Name:** Ensure the `name` in your `package.json` is available on NPM and that you have permission to publish to that scope (e.g., `@your-username/my-package`).

## Runtime Issues

These issues occur after your MCP server has been successfully deployed.

### Server Not Responding or Timing Out

**Symptom:** Your deployed MCP server does not respond to requests, or requests time out.

**Solution:**

1. **Check Runtime Logs:** This is the most critical step. Go to your project's **Logs** tab on the Deploxy Dashboard to see real-time logs from your server. Look for any startup errors or exceptions.
2. **Verify Environment Variables:** A missing or incorrect `injectedEnv` variable is a common cause of runtime failure. Go to your project's **Settings** tab to verify the environment variables for each region. Remember that any changes require a new deployment to take effect.
3. **Run a Health Check:** Use the health check feature on the **Settings** tab to confirm your serverless function is live.

### Environment Variables are `undefined`

**Symptom:** Your server crashes because `process.env.MY_VARIABLE` is `undefined`.

**Solution:**

1. **Check `.deploxy.json`:** Verify that the variable is defined in the `injectedEnv` section and that its value is a **string**.
2. **Redeploy:** Your server only receives new `injectedEnv` values after you run `npx @deploxy/cli deploy` again.

## Getting Help

If you're still stuck, we're here to help.

* **Community Support:** Join our [Discord Community](https://discord.gg/deploxy) for help from the community and the Deploxy team.
* **GitHub Issues:** If you believe you've found a bug in the CLI or platform, please open an issue on our [GitHub repository](https://github.com/deploxy/cli/issues).

When asking for help, please provide as much information as possible, including:

* The command you ran.
* The full output from the CLI (with any secrets redacted).
* Your (redacted) `.deploxy.json` and `package.json` files.
* Relevant snippets from your server code.