FAQ & Troubleshooting

Which parser should I use — OutputParser or a single-format parser?

Use a single-format parser (JSONOutputParser, YAMLOutputParser, etc.) when you know exactly what format to expect and want minimal overhead. Use OutputParser (the orchestrator) when the format is unpredictable, or you want automatic repair/retry/validation/audit-trail behavior. See Architecture → Two independent layers.

Why did parser.parse() return a dict with _parse_error: True instead of raising?

You're using ParseMode.LENIENT (the default). In LENIENT mode, total pipeline failure returns retry_graceful_fallback(text, original_prompt) — a safe dict with _parse_error: True, _raw, and _query keys — instead of raising ParseError. Switch to ParseMode.STRICT if you want a hard failure instead.

Why didn't SEMANTIC mode call my LLM?

ParseMode.SEMANTIC only triggers _semantic_parse() if llm_fn was provided to OutputParser(...). If llm_fn is None, the semantic branch is silently skipped and structural parsing runs instead — no warning or error is raised for this. Double-check llm_fn is set.

My JSON has apostrophes in string values and now OutputFixer breaks it further — why?

_fix_json_quotes (one step of the REGEX_REPAIR strategy) globally replaces every unescaped single quote with a double quote, intending to fix single-quoted JSON. If your JSON already used correct double quotes but a string value contains an apostrophe (e.g. "it's fine"), this step can corrupt that value. This is a known sharp edge of the regex-based repair pipeline — see fixer.md → Common Mistakes.

Why does PydanticOutputParser require pydantic but the rest of the package doesn't?

Only PydanticOutputParser and YAMLOutputParser (for pyyaml) hard-require their dependency at construction time. Everything else in schema.py and the JSON-based parsers checks availability at import time (PYDANTIC_AVAILABLE) and degrades gracefully (dataclass fallbacks instead of Pydantic models). See Installation → Optional dependencies.

Why does is_valid() return False even though I only see warnings in the results?

Check again — is_valid() returns False only if at least one result has status == ValidationStatus.FAILED. WARNING/SKIPPED/PASSED all count as "valid" for this method's purposes. If you're seeing False, there's a FAILED result somewhere in the list — inspect validator.get_failures(data) (note: this also includes WARNINGs, see next question).

get_failures() is returning warnings too, is that a bug?

No — this is the documented (if slightly surprising) behavior: get_failures() filters on not r.passed, and ValidationResult.passed is only True for PASSED. So WARNING and SKIPPED results are included in get_failures()'s output. If you specifically want hard failures, filter manually: [r for r in results if r.status == ValidationStatus.FAILED].

Does the cache in OutputParser expire?

No. OutputParser's in-memory _cache dict has no TTL or eviction policy — entries persist until you call clear_cache() or the instance is garbage collected. For long-running processes handling many unique inputs, either call clear_cache() periodically or construct with enable_cache=False.

Is this package thread-safe?

Mostly yes for read/config state, with one caveat: OutputParser._cache is a plain, unsynchronized dict, so concurrent parse() calls on the same instance can race on cache writes (benign in CPython — a lost update, not a crash). All other components (FormatDetector, OutputValidator, OutputFixer, RetryHandler, and the single-format toolkit parsers) hold only read-only config after construction and are safe to share across threads. See each API page's "Thread Safety" section for specifics.

Can I use this without an internet connection / without an LLM?

Yes — the entire single-format parser toolkit, FormatDetector, OutputFixer's non-LLM strategies (REGEX_REPAIR, FIELD_INJECTION, FALLBACK_PARSE), and OutputValidator work entirely offline on text you already have. Only SEMANTIC parse mode, the LLM_REFORMAT fix strategy, and RetryHandler require a live llm_fn.

Why is my required field always getting a default value instead of raising?

You may be relying on OutputFixer.fix_dict() / the FIELD_INJECTION strategy, which is designed to silently inject field_defaults.get(name, None) for any missing required field rather than raising. If you want missing-required-field detection to be a hard error, check OutputValidator's Layer 1 results (FieldSchema.validate_value returns FAILED for a missing required field with no default injected) rather than relying on the fixer to surface the absence.

Where can I report a bug or request a doc fix?

Not determinable from the analyzed source — no CONTRIBUTING.md, issue tracker link, or repository URL was present in the archive that this documentation was generated from.