Troubleshooting Guide

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.

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.

​

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 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.
   package.json

   {
     "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.
   package.json

   {
     "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 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.

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.