Known Limitations

Known Limitations

This page sets expectations for what ProxAI intentionally does not do today. It is a user-facing summary; exact protocol support lives in Compatibility Matrix, and exact configuration fields live in Configuration Reference.

Limitations are design boundaries

ProxAI is a small local compatibility proxy. It should not grow into a generic AI gateway unless the project explicitly chooses that direction.

Intentional non-goals

L1

Not a hosted gateway

ProxAI is designed for local compatibility and diagnostics, not multi-tenant hosting, account management, billing, or provider administration.

L2

Not a universal protocol converter

Only explicit protocol pairs are supported. Unsupported pairs fail explicitly instead of silently falling through.

L3

Not a prompt analytics platform

Default logs should stay compact and body-safe. Captures are local debugging artifacts, not product analytics.

L4

Not a provider control plane

Runtime behavior belongs in config.toml; ProxAI does not manage provider accounts or rotate provider credentials for users.

Practical limits

Area	Limit	Where to check
Protocol pairs	Support is pair-specific and direction-specific. Request, non-streaming response, and streaming support can differ.	Compatibility Matrix
Lossiness	Some conversions cannot preserve every source protocol concept exactly.	Lossiness and Fidelity
Streaming	Stream correctness depends on complete terminal events and provider event semantics.	Streaming Behavior
Tool calls	Started-but-unfinished streamed tool arguments are bounded by semantic timeout, not guessed into valid calls.	Status and Stop Reasons
Capture	Captures can contain private data and must stay local unless manually sanitized.	Privacy and Local Data
Provider quirks	Provider-local compatibility belongs in provider code; cross-protocol shape changes belong in translation.	Module Boundaries

If you hit a limit

1. Confirm the behavior in the relevant reference page.
2. Reproduce with the smallest request and the narrowest useful capture phase.
3. Decide whether the change belongs to provider compatibility, protocol translation, routing, or docs.
4. If it changes user-visible behavior, update both user docs and reference docs.

For local debugging paths, see Debugging Workflow and Troubleshooting.