Guides

This page applies the model to a real workflow. Open the guides overview

Debugging

Guide

Debugging with envctl works best when you stop guessing and inspect the model step by step: validation, profile selection, resolution, and finally projection.

When to use this guide

Use this page when:

• envctl behaves differently from what you expected
• the application sees the wrong value
• CI, Docker, or local runtime diverges
• you are not sure which layer is actually wrong

Starting point

Start with the smallest question first:

check first

$ envctl check

If validation fails, stay at that layer first. Do not debug a downstream runtime before the model is valid.

A practical debugging flow

1. Confirm the profile

Many “wrong value” problems are really “wrong profile” problems.

envctl --profile local check
envctl --profile dev-alt check

2. Inspect the key or the smallest useful scope

envctl inspect DATABASE_URL
envctl --group Runtime inspect
envctl --var DATABASE_URL inspect

Smaller surfaces make debugging faster.

3. Compare validation and projection

If check passes but the target process still behaves differently, the problem is usually no longer validation. It is projection.

4. Test the exact runtime handoff

envctl run -- python app.py
envctl export --format dotenv

Debug the path you actually use, not the one you assume exists.

Signals that usually matter

• validation fails → contract or local values are still wrong
• switching profile changes the result → the issue is local context selection
• inspect looks right but runtime does not → the issue is likely projection
• hooks or CI fail first → that is often a clue about where the mismatch appears

A useful rule

When something feels off, this order is usually enough:

1. validate with check
2. confirm the intended profile
3. inspect the key or subset that matters
4. test the real projection path
5. only then debug the downstream application itself

Read next

inspect

Use inspection commands when you need to stop guessing.

Open inspect reference

Resolution

Understand how envctl decides what is true at runtime.

Read about resolution

Common errors

See the most frequent failure shapes and their usual first move.

Open common errors