Pulumi Monorepo: Organize Infrastructure Code at Scale (2026)

Your Pulumi monorepo is failing because the pulumi CLI, when executing pulumi up or pulumi preview in a sub-directory, is unable to locate the necessary Pulumi.yaml file and its associated configuration. This happens because the CLI, by default, expects to be run from the root of a Pulumi project, not from within a subdirectory of a larger monorepo structure.

Common Causes and Fixes

Incorrect Working Directory:
- Diagnosis: When you run pulumi up from a subdirectory (e.g., ~/my-monorepo/services/api), the CLI looks for Pulumi.yaml in ~/my-monorepo/services/api and then its parent directories. If your Pulumi.yaml is at ~/my-monorepo/infrastructure/prod/api, it won’t be found.
- Fix: Navigate to the actual directory containing the Pulumi.yaml for the stack you intend to deploy.
```
cd ~/my-monorepo/infrastructure/prod/api
pulumi up
```
- Why it works: This ensures the Pulumi CLI is executed from the root of the specific Pulumi project it needs to manage.
Missing Pulumi.yaml in the Target Directory:
- Diagnosis: You might be in the correct monorepo root but trying to target a Pulumi project that doesn’t exist or hasn’t been created in the expected subdirectory.
- Fix: If you haven’t already, initialize a new Pulumi project in the desired location:
```
cd ~/my-monorepo/infrastructure/prod/api
pulumi new aws-typescript --name api-infra --yes
```
  This creates a Pulumi.yaml and the necessary project files.
- Why it works: This establishes a valid Pulumi project structure that the CLI can recognize and operate on.
Incorrect Stack Name or Configuration:
- Diagnosis: You’ve initialized a project, but when you try to pulumi up, it complains about missing stack configuration or an invalid stack name. This often happens if you’re not explicit about which stack you’re targeting, especially in a monorepo.
- Fix: Ensure you are setting the correct stack name when running commands, or that the Pulumi.yaml correctly points to a default stack. If you’ve created multiple stacks (e.g., dev, staging, prod) within a single project, you need to specify which one:
```
cd ~/my-monorepo/infrastructure/prod/api
pulumi stack select prod # Or your specific stack name
pulumi up
```
  Or, if you’re using a different default stack name:
```
cd ~/my-monorepo/infrastructure/prod/api
pulumi stack init dev # To initialize a stack named 'dev'
pulumi up
```
- Why it works: Pulumi organizes deployments by stacks. Explicitly selecting or initializing a stack ensures the CLI knows which set of configuration and resources to manage.
Global vs. Project-Specific Configuration:
- Diagnosis: You might have global Pulumi configuration set (e.g., AWS region) that conflicts with or is insufficient for your project’s specific needs, leading to errors during deployment.
- Fix: Ensure project-specific configuration is set correctly. This is often done via Pulumi.<stack-name>.yaml files. For example, to set the AWS region for your prod stack:
```
cd ~/my-monorepo/infrastructure/prod/api
pulumi config set aws:region us-east-1 --stack prod
pulumi up
```
- Why it works: Project and stack-specific configuration overrides global settings, ensuring your infrastructure is deployed with the exact parameters required for that environment.
Monorepo Tooling Interference (e.g., Lerna, Nx):
- Diagnosis: If you’re using monorepo management tools, they might inadvertently change the working directory or environment variables in a way that confuses the Pulumi CLI. For instance, a tool might run a command from the monorepo root, expecting Pulumi commands to also run from there, but your Pulumi.yaml is nested deeper.
- Fix: When invoking Pulumi commands through your monorepo tool, ensure the cwd (current working directory) is set correctly to the directory containing the Pulumi.yaml for the specific project.
  - Example with Nx: In your project.json for the Pulumi project:
```
{
  "targets": {
    "deploy": {
      "executor": "nx:run-commands",
      "options": {
        "cwd": "apps/infrastructure/api", // Path to your Pulumi.yaml
        "command": "pulumi up --stack dev"
      }
    }
  }
}
```
  - Example with Lerna: In your lerna.json or a script:
```
// In package.json script
"scripts": {
  "deploy:api": "lerna run --scope @my-org/api-infra -- pulumi up --stack prod --cwd ./packages/api-infra"
}
```
- Why it works: This explicitly tells the monorepo tool to execute the Pulumi command with the correct context, resolving potential working directory mismatches.
Environment Variable Conflicts or Missing Variables:
- Diagnosis: Pulumi relies on environment variables for certain configurations (e.g., PULUMI_CONFIG_PATH, cloud provider credentials). If these are not set correctly in the environment where pulumi up is executed, or if they are being overridden by other processes, it can cause failures.
- Fix: Explicitly set or verify necessary environment variables before running Pulumi commands, especially when running within CI/CD pipelines or complex build environments.
```
export ARM_CLIENT_ID="your-client-id"
export ARM_CLIENT_SECRET="your-client-secret"
export ARM_TENANT_ID="your-tenant-id"
export ARM_SUBSCRIPTION_ID="your-subscription-id"
export PULUMI_BACKEND_URL="https://api.pulumi.com/your-org/your-project" # If using a self-hosted backend or specific project
cd ~/my-monorepo/infrastructure/prod/api
pulumi up
```
- Why it works: Ensures Pulumi has all the necessary external context and credentials to authenticate with cloud providers and access its state backend.

The next error you’ll likely encounter after fixing these issues is related to state backend access or permissions, where Pulumi cannot read or write its state file, typically due to misconfigured credentials or network connectivity problems to the backend service (like AWS S3, Azure Blob Storage, or Pulumi Service).