FAQ

What happens if I call penvload with a path that doesn’t exist?

By default (createFile: true), penv writes a placeholder template file to that path and throws EnvFileNotFoundException. Fill in the new file and run your program again. Pass createFile: false to skip writing anything and just get the exception, or use penvloadOrNull to get null back instead of an exception.

Does penv overwrite my .env file if it already exists?

No — the placeholder-file behavior only triggers when the file is missing. An existing file, however malformed, is read and parsed as-is; malformed lines are simply skipped (see Env File Syntax) rather than causing penv to touch the file.

Why is my value truncated after a #?

Unquoted values have a trailing # comment stripped, matching common .env convention. If your value should genuinely contain a #, wrap it in quotes: TAG="v1.0#beta".

Why didn’t ${OTHER_KEY} expand?

Two likely reasons: the value is single-quoted (single-quoted values are never expanded — see Env File Syntax), or OTHER_KEY is defined later in the file than the line referencing it. Expansion only looks at keys already parsed earlier in the same file, then the process environment — reorder the file so the referenced key comes first.

Does penv pull in my entire shell environment?

No. useProcessEnvironment only overlays values onto keys that already exist in the parsed file — it never adds keys that aren’t already declared there, so unrelated system variables like PATH or HOME never leak into the result.

Why does getInt/getBool/getString throw instead of returning null?

To surface misconfiguration immediately and clearly, with a message naming the exact key, rather than deferring a null-check crash to wherever the value is eventually used. Pass defaultValue for anything genuinely optional.

Where do I report a bug or ask a question?

GitHub Issues — see Contributing.