zylon-ai/private-gpt · error · ValueError

INVALID_REQUEST_ERROR

INVALID_REQUEST_ERROR

Error message

Unsupported format strategy: {selected_format_strategy}. Supported strategies are: 'list', 'xml', 'json'.

What it means

ValueError from the citations formatter's match statement: for document-type context, selected_format_strategy must be one of 'list', 'xml', or 'json' — each routed to a dedicated _format_documents_as_* function. Any other string falls to the catch-all arm and is rejected with the supported set spelled out. Tagged INVALID_REQUEST_ERROR, meaning the strategy value came from (or derives from) request input.

Source

Thrown at private_gpt/components/engines/citations/format.py:458

                    return _format_documents_as_xml(
                        documents,
                        start_token=start_token,
                        end_token=end_token,
                        generate_citations=generate_citations,
                        token_limit=token_limit,
                        tokenizer_fn=tokenizer_fn,
                    )
                case "json":
                    return _format_documents_as_json(
                        documents,
                        start_token=start_token,
                        end_token=end_token,
                        generate_citations=generate_citations,
                        token_limit=token_limit,
                        tokenizer_fn=tokenizer_fn,
                    )
                case _:
                    raise ValueError(
                        f"Unsupported format strategy: {selected_format_strategy}."
                        f" Supported strategies are: 'list', 'xml', 'json'."
                    )

        case "webpage":
            return _format_website_as_list(
                documents,
                start_token=start_token,
                end_token=end_token,
                generate_citations=generate_citations,
                token_limit=token_limit,
                tokenizer_fn=tokenizer_fn,
            )
        case _:
            raise ValueError(
                f"Unsupported document type: {type}. Supported types are: 'document'."
            )

View on GitHub (pinned to 4a030776a3)

Solutions

  1. Set the strategy to exactly 'list', 'xml', or 'json' (lowercase)
  2. Normalize/lowercase and validate the strategy string at the API boundary before it reaches the formatter
  3. If a client sends an unknown strategy, map old names to current ones or reject with the supported list
  4. Check the response/prompt-format settings block for a stale strategy value

Example fix

# before
fmt = format_documents(docs, format_strategy='markdown')  # ValueError

# after
fmt = format_documents(docs, format_strategy='json')
Defensive patterns

Strategy: validation

Validate before calling

ALLOWED_STRATEGIES = {'list', 'xml', 'json'}
strategy = (strategy or '').lower().strip()
if strategy not in ALLOWED_STRATEGIES:
    raise ValueError(f'format_strategy must be one of {sorted(ALLOWED_STRATEGIES)}')

Type guard

def is_supported_format_strategy(s: str) -> TypeGuard[str]:
    return s in {'list', 'xml', 'json'}

Try / catch

try:
    formatted = format_documents(docs, format_strategy=strategy)
except ValueError as e:
    if 'Unsupported format strategy' in str(e):
        return error_response(400, str(e))
    raise

Prevention

When it happens

Trigger: Calling the format routine (directly or via chat/citation settings) with format_strategy set to something like 'markdown', 'text', 'JSON' (uppercase), or '' while document-type documents are being formatted.

Common situations: User-supplied or API-supplied format parameter passed through unvalidated; casing/typo differences ('Xml'); stale client sending a strategy name removed in a newer server version; config defaults referencing an old name.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/af32dd4a1ad229e3. Report an issue: GitHub.