## TL;DR

Hand-rolled .env parsers break on quoted multiline values, escapes, and comments. Use a proper dotenv library, and keep multiline values quoted per the format.

## Error

```text
agent failed to parse the .env file: multiline value broke the parser error
```

## Steps

1. Find the breaking value: usually a quoted multiline string or an escaped character. Expected: the trigger identified.
2. Replace the hand-rolled parser with a maintained dotenv library. Expected: correct parsing.
3. Quote multiline values and keep them on logical lines per the format. Expected: the file parses.
4. Add a parse check to CI so broken .env files fail fast. Expected: early detection.
5. Re-run the agent. Expected: clean parse.

## When to use

- .env parsing failures in agents.
- Hardening config parsing.

## When not to use

- The file is missing (different error).
- Values are wrong but parse fine (data issue).

## Tool compatibility

- Dotenv libraries per language.

## Variant phrasings

### multiline .env broke parser

Use a real parser.

### dotenv parse error

Same fix.

## Why it happens

The .env format has quoting, escaping, and comment rules that naive line-splitting gets wrong.

## Edge cases

- Different libraries handle edge cases differently; pick one and standardize.
- Secrets in .env files should move to a manager; the parser fix is tactical.
- Never log parsed values; log keys only.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_i4JgI1Vt1TMYCK24f5L64w