www/apps/cloud/app/deployments/troubleshooting/page.mdx
import { Note, InlineIcon } from "docs-ui" import { EllipsisHorizontal } from "@medusajs/icons"
export const metadata = {
title: Troubleshooting Cloud Deployments,
}
In this guide, you'll find solutions to common issues that may arise when deploying your Medusa applications on Cloud.
When your build or deployment fails on Cloud, you can use the "Fix with AI" feature to troubleshoot and resolve the issue with the help of Cloud's support agent. The AI agent will analyze the deployment and build logs, identify the root cause of the issue, and provide you with actionable steps to resolve it.
Learn more in the Fix Deployment and Build Issues with AI guide.
When a deployment fails, you can see the build and runtime logs of your deployment to understand the cause of the failure.
Alternatively, you can install the Cloud CLI and use it to check logs from your terminal or with the help of AI agents like Claude Code.
For example:
# Install the CLI
npm install @medusajs/mcloud -g
# Login
mcloud login
# Check logs of the latest deployment in the environment
mcloud logs --organization org_123 --project proj_123 --environment env_123
# Check logs of a specific deployment
mcloud logs --organization org_123 --project proj_123 --environment env_123 --deployment-id deploy_123
See the Cloud CLI guide for more details on how to use the CLI to manage your Cloud resources and deployments.
Before deploying your Medusa application on Cloud, Medusa runs the build script defined in your package.json file, then copies only the output of the build process, which is the .medusa/server directory.
The .medusa/server directory holds the compiled JavaScript files of your project, the production build of the admin dashboard, and other necessary files to run your Medusa application in production.
If you have custom files needed at runtime, such as a src/data directory that holds JSON files, modify the build script in your package.json file to copy these files to the .medusa/server directory after the build process.
For example:
{
"scripts": {
"postbuild": "cp -r src/data .medusa/server/src/data",
"build": "medusa build && npm run postbuild"
}
}
This script copies the src/data directory to the .medusa/server directory following the build process.
Learn more in the Deployments Guide.
<Note>You can replace npm run postbuild with the appropriate command for your package manager, such as yarn postbuild.
If your deployment fails with an error similar to:
Invalid build output: missing /build/apps/backend/.medusa/server/medusa-config.js.
Ensure tsconfig compilerOptions.outDir is .medusa/server (or unset), your package.json
build script runs medusa build, and the Medusa build step completed successfully.
Cloud validates that the Medusa build output contains a compiled medusa-config.js file at .medusa/server/medusa-config.js. This file is produced when medusa build compiles your medusa-config.ts file to the .medusa/server directory.
The error occurs when one of the following is true:
build script in package.json does not run medusa build.tsconfig.json file sets compilerOptions.outDir to a path other than .medusa/server, causing the build output to land in the wrong directory.medusa build step failed silently or was skipped during the build.Open your package.json and confirm the build script calls medusa build:
{
"scripts": {
"build": "medusa build"
}
}
If you have a custom post-build step, chain it after medusa build:
{
"scripts": {
"build": "medusa build && npm run postbuild"
}
}
Open tsconfig.json and check the compilerOptions.outDir value. Either remove it to use the default (.medusa/server), or set it explicitly to .medusa/server:
{
"compilerOptions": {
"outDir": ".medusa/server"
}
}
Setting outDir to any path other than .medusa/server causes the build output to land in the wrong location and triggers this error.
After verifying the script and tsconfig.json, check the build logs to confirm medusa build ran and completed without errors. If you see TypeScript compilation errors in the logs, fix them locally by running:
npm run build
Then commit the fixes and push to trigger a new deployment.
Exit code 137 indicates that your build process was killed by the system due to memory exhaustion. This commonly occurs with TypeScript-heavy monorepos during compilation.
Check your build logs for these indicators:
OOM Build failures typically occur when the TypeScript compiler faces complex types in your project. This commonly happens when there's mismatch between dependencies in your project.
For example, Medusa supports Zod v4.2.0. If you install a different version of Zod in your project, it can lead to complex type issues during compilation, causing OOM failures.
To resolve this, ensure that your project's dependencies are compatible with those used by Medusa or other dependencies.
If your Yarn berry monorepo build fails with the following error, the yarn.lock file is not included in the build context:
failed to calculate checksum of ref: "/yarn.lock": not found
This is different from an outdated lockfile. The lockfile is entirely absent from the build context. Cloud cannot install dependencies without it.
The most common cause is that yarn.lock is listed in .gitignore or was never committed to the repository.
yarn install locally to generate the lockfile:yarn install
yarn.lock file to your repository:git add yarn.lock
git commit -m "Add yarn.lock"
git push
Always commit your lockfile to version control. Cloud requires the lockfile to install dependencies with a frozen install, ensuring reproducible builds. Remove any line in your .gitignore that matches yarn.lock or *.lock.
If your build fails with the following error, your pnpm-lock.yaml file is out of sync with package.json:
ERR_PNPM_OUTDATED_LOCKFILE Cannot install with 'frozen-lockfile' because
pnpm-lock.yaml is not up to date with package.json
Cloud uses --frozen-lockfile when installing dependencies to ensure reproducible builds. This means the lockfile must be committed and kept up to date with package.json.
To fix this error:
pnpm install locally to update the lockfile.pnpm-lock.yaml file.If your build fails with the following error, your yarn.lock file is out of sync with package.json:
YN0028: The lockfile would have been modified by this install,
which is explicitly forbidden.
or
YN0086: Some peer dependencies are incorrectly met by your project;
run yarn explain peer-requirements <hash> for details, where <hash>
is the six-letter p-prefixed code.
Medusa uses --frozen-lockfile (also known as immutable installs) during Cloud builds to ensure reproducible deployments. This means the yarn.lock file must be committed and kept in sync with your package.json. The error occurs when you add or update a dependency in package.json without running yarn install locally and committing the updated lockfile.
To fix this error:
yarn install locally to update the lockfile:yarn install
yarn.lock file:git add yarn.lock
git commit -m "Update yarn.lock"
git push
If your storefront build fails with a build-failed status but the build logs are empty or show minimal output, the cause is usually one of the following:
package.jsonCloud installs dependencies with a frozen lockfile to ensure reproducible builds. If your lockfile is out of sync with package.json, the dependency installation step may fail silently.
To check and fix a lockfile mismatch:
npm install
When the Cloud dashboard shows minimal or empty build logs, use the Cloud CLI to retrieve the full output:
# Install the CLI
npm install @medusajs/mcloud -g
# Login
mcloud login
# List recent deployments to find the failed deployment's ID
mcloud deployments list \
--organization org_123 \
--project proj_123
# Fetch the storefront build logs for a specific deployment
mcloud deployments build-logs deploy_123 \
--organization org_123 \
--project proj_123 \
--type storefront
Replace org_123, proj_123, and deploy_123 with your actual IDs. You can find the deployment ID in the output of mcloud deployments list or in the Cloud dashboard's deployment details page.
If neither of the steps above resolves the issue and the storefront build logs remain empty, contact support and include the deployment ID so the team can investigate at the platform level.
When you install a third-party package (for example, a payment provider) that requires a specific version of a Medusa package, npm may throw an ERESOLVE error if the required version doesn't match the version installed in your project.
For example, you may see an error similar to:
npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: [email protected]
npm error Found: @medusajs/[email protected]
npm error node_modules/@medusajs/framework
npm error @medusajs/framework@"2.15.5" from the root project
npm error
npm error Could not resolve dependency:
npm error peer @medusajs/framework@"2.13.6" from @example/[email protected]
Try the following strategies in order:
npm install @example/medusa-payment-example@latest
Contact the package maintainer: If no compatible version exists, open an issue or contact the maintainer to request support for your Medusa version.
Use --legacy-peer-deps: If the version mismatch is minor (for example, a patch version difference) and you have confirmed the package works correctly, you can bypass the conflict. Add the following to a .npmrc file at the root of your project:
legacy-peer-deps=true
This tells npm to ignore peer dependency conflicts and install anyway. Use this as a last resort, and test your integration thoroughly before deploying.
<Note type="warning">Using --legacy-peer-deps may introduce compatibility issues. Always test your application thoroughly after applying this workaround.
If your build fails with the following error, the patchedDependencies configuration in your package.json does not match what is recorded in pnpm-lock.yaml:
ERR_PNPM_LOCKFILE_CONFIG_MISMATCH Cannot proceed with the frozen installation.
The current "patchedDependencies" configuration doesn't match
the value found in the lockfile
This happens when you add, remove, or modify patch files in the patches/ directory without regenerating the lockfile. Cloud uses --frozen-lockfile for reproducible builds, so the lockfile must reflect the current patch configuration.
To fix this error:
pnpm install locally to regenerate the lockfile.pnpm-lock.yaml file.If your storefront or backend build fails with an authentication error like the following, your private npm registry credentials are not available during the build:
ERR_PNPM_FETCH_401 GET https://registry.example.com/my-package:
Response was 401 Unauthorized
This occurs when packages are hosted on a private registry (for example, a company Artifactory instance or a scoped registry) and the build environment does not have the credentials to fetch them.
To provide registry credentials to Cloud builds:
NPM_TOKEN with your token value..npmrc file, reference the environment variable://registry.example.com/:_authToken=${NPM_TOKEN}
.npmrc file to your repository.The .npmrc file must be committed to your repository for Cloud to use it during builds. The environment variable is injected at build time.
If the private registry authentication fails, pnpm install may fail silently or produce cryptic secondary errors such as missing binaries or missing modules. If you see unexpected errors after a build, check the build logs for 401 Unauthorized or ERR_PNPM_FETCH_401 errors earlier in the output.
If your Cloud build fails with exit code 1 during the pnpm install step and the error message only says "process did not complete successfully", the cause is often a lockfile or dependency issue that is hidden in pnpm's full output.
Cloud uses --frozen-lockfile when installing dependencies to ensure reproducible builds. This means your pnpm-lock.yaml must be committed and kept in sync with package.json.
pnpm-lock.yaml file was not committed after updating package.json.The Cloud dashboard may truncate build output. Use the Cloud CLI to retrieve the full pnpm install logs:
# Install the CLI
npm install @medusajs/mcloud -g
# Login
mcloud login
# List recent deployments to find the failed deployment ID
mcloud deployments list \
--organization org_123 \
--project proj_123
# Fetch the full build logs
mcloud deployments build-logs deploy_123 \
--organization org_123 \
--project proj_123
Replace org_123, proj_123, and deploy_123 with your actual IDs.
If the logs show a lockfile error, regenerate the lockfile locally:
pnpm install locally to update the lockfile.pnpm-lock.yaml.If you're using a Next.js 16 storefront with a middleware, also known as proxy, your build will fail with the following error:
ERROR Node.js middleware is not currently supported. Consider switching to Edge Middleware.
This is because Cloud does not currently support Node.js middlewares in Next.js 16. You can either:
If your build fails with an error similar to:
npm error code EEXIST
npm error syscall open
npm error path /root/.npm/_cacache/tmp/...
npm error errno -17
npm error EEXIST: file already exists, open '/root/.npm/_cacache/tmp/...'
This is a transient npm cache corruption or a race condition in Docker's cache mount. The build environment's npm cache becomes temporarily inconsistent, causing npm ci to fail when writing temporary files.
Retry the build. The error is transient and the build typically succeeds on the second attempt.
To retry a deployment from the Cloud dashboard:
If the error persists across two or three consecutive builds, contact support to clear the npm cache for your project.
</Note>If your deployment fails with a database connection error such as KnexTimeoutError or Pg connection failed to connect to the database, the most common cause is a missing or misconfigured DATABASE_URL environment variable.
Medusa automatically provisions and manages the database for each environment on Cloud. You do not need to create or configure a database yourself. The DATABASE_URL is set automatically by Cloud when your environment is created.
If you have manually set a DATABASE_URL in your environment variables, it may conflict with the one Cloud sets automatically. To resolve this:
DATABASE_URL variable set. If so, remove it and let Cloud manage the connection string.To troubleshoot other Cloud deployment issues, you can: