🚨 Pulumi Error: 'no Pulumi.yaml project file found' — Cause, Fix, and Troubleshooting Guide

Overview

error: no Pulumi.yaml project file found means the pulumi CLI could not locate a project manifest for the command you ran. Every Pulumi project is defined by a Pulumi.yaml file at its root. Almost all commands — up, preview, stack, config, destroy — must be run from inside a project, and Pulumi discovers that project by searching the current working directory and walking up its parents for a Pulumi.yaml.

error: no Pulumi.yaml project file found (searching upwards from /home/james/work). If you have not created a project yet, use `pulumi new` to do so: no project file found

If Pulumi reaches the filesystem root without finding a Pulumi.yaml, you get this error. It is almost always a “wrong directory” or “never initialized” problem, not a bug.

Symptoms

• Any pulumi command (except a few global ones like pulumi version or pulumi login) fails immediately with no Pulumi.yaml project file found.
• The message shows the directory Pulumi searched upward from.
• You just cloned a repo, or cd’d into the wrong subfolder, or opened a fresh shell in $HOME.
• A CI job runs pulumi up from the repo root while Pulumi.yaml lives in a subdirectory.

Common Root Causes

1. You are in the wrong directory

You are running pulumi from your home directory, the repo root, or a sibling folder rather than the directory that contains Pulumi.yaml.

pwd            # /home/james  — no Pulumi.yaml here

2. The project was never created

You installed the CLI but never ran pulumi new, so no Pulumi.yaml exists yet.

3. Pulumi.yaml lives in a subdirectory (monorepo layout)

The manifest is under infra/ or deploy/, but CI or your shell invokes Pulumi from the repository root.

repo/
  app/
  infra/
    Pulumi.yaml   <-- run pulumi from here, not from repo/

4. The file was renamed, deleted, or not committed

Pulumi.yaml is case-sensitive and must be spelled exactly. A pulumi.yaml (lowercase), a .gitignore that excluded it, or an accidental deletion all produce this error.

How to Diagnose

Confirm where you are and whether a manifest exists nearby:

pwd
ls -la Pulumi.yaml
find . -maxdepth 3 -name Pulumi.yaml

If find locates the file in a subdirectory, that subdirectory is your project root. Verify the file is well formed and has the required name and runtime keys:

cat Pulumi.yaml

A minimal valid manifest looks like this:

name: myproject
runtime: nodejs
description: A minimal Pulumi program

Fixes

If the project exists — cd into the directory that holds Pulumi.yaml. This is the most common fix.

cd infra
pulumi stack ls
pulumi up

Point Pulumi at the project directory without changing directories. Use the global --cwd (-C) flag, which is ideal for CI:

pulumi up --cwd infra

If no project exists — create one with pulumi new. This scaffolds a valid Pulumi.yaml, a runtime program, and a first stack:

mkdir infra && cd infra
pulumi new aws-typescript

Run pulumi new --list-templates to see available templates (for example aws-python, gcp-go, azure-csharp, or yaml).

If the manifest was renamed or lowercased — restore the exact filename. Pulumi requires Pulumi.yaml (capital P, .yaml extension):

mv pulumi.yaml Pulumi.yaml

Recreate a minimal manifest by hand if it was lost but the program code survives. At minimum it needs name and runtime:

name: myproject
runtime: python
description: Restored project manifest

What to Watch Out For

• The filename is case-sensitive: Pulumi.yaml, not pulumi.yaml or Pulumi.yml.
• Pulumi.yaml (the project) is different from Pulumi.<stack>.yaml (per-stack config). You need the former; the latter is optional and auto-created by pulumi config set.
• Make sure Pulumi.yaml is committed and not caught by .gitignore — a fresh clone that lacks it will fail in CI even though it works locally.
• In monorepos, always set the working directory explicitly (--cwd, or cd) so the project root is unambiguous.
• The manifest must contain valid YAML with the required name and runtime fields, or Pulumi will reject it even when the file is present.

Related Guides

• Pulumi Error: ‘failed to register new resource’ — Troubleshooting Guide
• Pulumi Error: ‘could not load plugin’ — Troubleshooting Guide
• Pulumi Error: ‘the stack is currently locked by 1 lock(s)’ — Troubleshooting Guide