🧱 Pulumi Error: 'error parsing Pulumi.yaml' — Invalid YAML Program Fix

Exact Error Message

error: error parsing Pulumi.yaml: could not unmarshal YAML:
    yaml: line 14: did not find expected key

error: could not load Pulumi.yaml: invalid YAML program

You may also see yaml: line N: found character that cannot start any token (usually a tab), mapping values are not allowed in this context, or error: resource my-bucket: property "type" is required. All indicate the YAML program or project file could not be parsed or validated.

What It Means

Pulumi’s YAML runtime treats Pulumi.yaml itself as the program: the resources, variables, and outputs sections declare your infrastructure directly in YAML. Before Pulumi can plan anything, it has to parse that YAML and validate it against the program schema. “error parsing Pulumi.yaml” means the parser hit malformed YAML — bad indentation, a tab character, an unquoted special character — or the structure did not match what the schema expects (for example a resource missing its type).

This is a document-syntax or schema-shape problem, not a provider or credentials issue. The fix is to make the YAML both valid and well-formed for the Pulumi program schema.

Common Causes

• Inconsistent indentation or a tab character (YAML requires spaces).
• A value containing a special character (:, {, @) left unquoted.
• A resource entry missing the required type key, or properties misindented under it.
• Broken interpolation syntax — ${...} references that are malformed or point at an undefined name.
• A duplicate key in a mapping (two resources or two properties with the same name).
• A misplaced top-level key so resources/outputs nest under the wrong parent.

Diagnostic Commands

Validate the raw YAML syntax independently of Pulumi:

python3 -c "import yaml,sys; yaml.safe_load(open('Pulumi.yaml'))"

Reveal hidden tabs and trailing whitespace that break parsing:

grep -nP "\t" Pulumi.yaml
cat -A Pulumi.yaml | head -n 40

Let Pulumi report the exact line and validation error:

pulumi preview

Confirm the runtime is actually yaml:

head -n 5 Pulumi.yaml

Step-by-Step Resolution

1. Read the reported line number. did not find expected key and mapping values are not allowed almost always point at an indentation or missing-colon problem on or just above that line.

2. Replace any tabs with spaces and make indentation consistent (two spaces per level is conventional):

sed -i 's/\t/  /g' Pulumi.yaml

3. Quote values that contain special characters so the parser does not misread them:

variables:
  connString: "host:5432,ssl:true"   # colons must be quoted

4. Give every resource a type and nest properties correctly. A valid resource block looks like this:

name: my-app
runtime: yaml
resources:
  data-bucket:
    type: aws:s3:Bucket
    properties:
      acl: private
outputs:
  bucketName: ${data-bucket.id}

5. Fix interpolation references so ${...} names an actual resource or variable declared in the file, and remove duplicate keys.

6. Re-validate and preview:

python3 -c "import yaml; yaml.safe_load(open('Pulumi.yaml'))" && pulumi preview

If a nested resources block is hard to structure, describe what you are building and let a prompt from the Pulumi prompt library generate a schema-correct YAML skeleton to compare against.

Prevention

• Use an editor with YAML linting (yamllint or an IDE plugin) so tabs and indentation errors surface as you type.
• Configure your editor to insert spaces, never tabs, and to show whitespace.
• Quote any string containing :, {, }, @, or a leading %/&/*.
• Keep the resource schema handy: every resource needs type, and properties nests one level under it.
• Run a yaml.safe_load (or yamllint) check in CI before pulumi preview so parse errors fail fast.

Related Errors

• no Pulumi.yaml project file found — the file is missing or you are in the wrong directory, not a parse error.
• resource ...: property "type" is required — valid YAML but an incomplete resource block.
• unknown provider type — the YAML parsed but names a type no installed provider supports.
• invalid config key — a config/variables reference that does not resolve.

Frequently Asked Questions

Why does Pulumi parse Pulumi.yaml as a program? With runtime: yaml, the project file is the program — the resources and outputs sections declare infrastructure directly, so it must parse and validate before planning.

What causes found character that cannot start any token? Almost always a literal tab character; YAML forbids tabs for indentation, so replace them with spaces.

How do I reference one resource from another? Use ${resourceName.property} interpolation (for example ${data-bucket.id}), and make sure the referenced name is declared in the same file.

Is a YAML program less capable than TypeScript or Go? It is simpler and great for straightforward stacks, but you can convert to a full language later with pulumi convert. For more YAML program guidance, see the Pulumi guides.