The agent starts generating. Mid-sentence, it stops. "Response truncated due to output length limit." The output is useless. The conversation is broken. Here are five causes from real GitHub issues and the fix for each.
A Chinese user posted on X during Labor Day weekend: "My Hermes keeps throwing 'Response truncated due to output length limit.' I've given up on it. Let it starve."
That's the vibe. The error is maddening because it looks like a simple limit you should be able to increase. But max_tokens in config.yaml had no effect until recently. The compression system has a math bug that prevents it from firing. And the hardcoded output limits can drain your OpenRouter credits before the model generates a single token.
GitHub issue #7237 documents the core complaint: "This truncates the output mid-stream, breaks the conversation flow, and prevents users from receiving complete, usable answers."
Here are five causes, ranked by how often they're the actual problem.
Cause 1: max_tokens from config.yaml never reaches the API (confirmed bug)
GitHub issue #4404: "model.max_tokens in config.yaml has no effect. The setting is never passed to AIAgent."
What happens: You set model.max_tokens: 8192 in your config. The agent ignores it. The API request goes out without max_tokens. The provider uses its default (often 2,048 or 4,096). Your response gets truncated at a limit you didn't set.
The bug confirmed: A developer patched the code to log what _build_api_kwargs() actually sends. Result: self.max_tokens=None. The config value exists but the code path from config.yaml → AIAgent → API request is broken.
The fix: A community PR exists on fix/model-max-tokens-config branch. If you're on v0.13.0+, check if the fix is merged. If not, the workaround: set HERMES_MAX_TOKENS=8192 as an environment variable in ~/.hermes/.env. The env var path works even when the config path doesn't.
The frustrating truth: The most common cause of truncation is a config value that looks correct but is silently ignored. Always verify with hermes chat -q "write a 500-word essay" --verbose and check the API request logs for the actual max_tokens value sent.
Cause 2: Provider default output limit is too low (especially Ollama)
What happens with Ollama: The default context window is 2,048 tokens. Not 8,192. Not the model's maximum. Two thousand and forty-eight. A 500-word response easily exceeds this.
The fix for Ollama: Create a Modelfile that sets the correct limits:
FROM hermes3:8b
PARAMETER num_ctx 8192
PARAMETER num_predict 1024
num_ctx is the total context window. num_predict is the max output tokens. Without these, Ollama defaults to 2,048 total, leaving almost no room for output after the system prompt and conversation history consume their share.
For the complete model configuration guide, our best practices post covers per-model output limit configuration.
Cause 3: Context window full (no room left for output)
Here's where most people get it wrong.
The context window is shared between input and output. If your model has a 64K context window and your conversation history + system prompt + tool definitions consume 60K tokens, only 4K tokens remain for the response. The model starts generating, hits the ceiling at 4K, and truncates.
The fix: Run /usage in your chat to see current context consumption. If you're above 70%, run /compress to summarize the conversation history and free space. Or start a new session with hermes chat --new.
The official FAQ confirms: "Use /compress regularly during long sessions. It summarizes the conversation history and reduces token usage significantly while preserving context."
Cause 4: Compression never triggers (the math bug)
GitHub issue #14690 (P1, open): "Context auto-compression never triggers when context_length equals MINIMUM_CONTEXT_LENGTH (64000)."
The bug: The compression threshold calculation uses 64,000 as an absolute floor. If your model's context is 64K (common for local models with parallel slots), the threshold becomes 100% of the context window. Compression can't trigger because the API errors out before the threshold is reached.
The math: threshold_tokens = max(int(64000 * 0.7), 64000) = max(44800, 64000) = 64000. Threshold = 100%. Compression never fires. Context grows until the API rejects the request. Response gets truncated.
The fix: Set model.context_length in config.yaml to a value above 64,000 (e.g., 128000) so the threshold calculation produces a meaningful percentage. Or manually run /compress before the context fills.
If debugging config values that are silently ignored, Ollama defaults that nobody documents, context window math bugs, and compression thresholds that never trigger sounds like more framework internals than agent building, BetterClaw's smart context management handles all of this at the platform level. No max_tokens configuration. No compression commands. No context math. The platform manages output limits and context automatically. Free tier with 1 agent and BYOK. $19/month per agent for Pro.
Cause 5: Hardcoded max_tokens reserves too many credits on OpenRouter
GitHub issue #22879: "Hermes hardcodes max_tokens to each model's maximum output (e.g., 64000 for Claude Sonnet/Haiku 4.5). OpenRouter reserves the full max_tokens as collateral before allowing the call."
What happens: You have $10 in OpenRouter credits. Hermes requests max_tokens=64000. OpenRouter reserves $10+ worth of credits upfront. Your balance can't cover the reservation. OpenRouter returns HTTP 402 ("requires more credits"). The actual response would be 50-500 tokens. The reservation is 64,000.
The fix: This is tagged as a feature request (#22879). Until it's resolved, add more credits to your OpenRouter account (enough to cover the worst-case reservation), or switch to a direct provider (Anthropic direct doesn't pre-reserve credits).
The diagnostic checklist
Step 1: hermes chat -q "write a 500-word essay" --verbose ... Check the API request for actual max_tokens value.
Step 2: /usage in an active chat ... How much context is consumed? If above 70%, run /compress.
Step 3: Check your Ollama Modelfile ... Is num_ctx set? Is num_predict set? Defaults are too low.
Step 4: Check model.context_length in config.yaml ... Is it 64,000? If so, the compression bug (#14690) applies.
The truncation error is Hermes's way of saying "the model ran out of room." But "ran out of room" has five different causes, and the error message doesn't tell you which one. Config values that are ignored. Provider defaults that are undocumented. Context that fills silently. Compression that can't fire. Credit reservations that block the call. Same error. Five different problems.
If you want an agent where context management is handled automatically and you never see "response truncated," give BetterClaw a try. Free tier with 1 agent and BYOK. $19/month per agent for Pro. Smart context management. No truncation. No compression commands. The agent speaks. The response completes.
Frequently Asked Questions
What does "Response truncated due to output length limit" mean in Hermes?
It means the model's response was cut off before completion. The five causes: max_tokens config not being sent to the API (bug #4404), provider default output limit too low (Ollama defaults to 2,048), context window full with no room for output, compression math bug preventing auto-compression (#14690), or OpenRouter credit reservation blocking the call (#22879).
How do I increase the output length in Hermes Agent?
Set HERMES_MAX_TOKENS=8192 in ~/.hermes/.env (the config.yaml path may not work due to bug #4404). For Ollama, create a Modelfile with PARAMETER num_ctx 8192 and PARAMETER num_predict 1024. For cloud providers, verify the max_tokens value in verbose logs. Use /compress regularly to free context space during long sessions.
Why does /compress not work in Hermes?
If your model's context_length equals 64,000 (the MINIMUM_CONTEXT_LENGTH constant), auto-compression never triggers due to a math bug (#14690, P1, open). The threshold calculation produces 100% of the context window, which is unreachable. Fix: set model.context_length in config.yaml to a value above 64,000 (e.g., 128000) so the threshold calculation works correctly.
Why does Hermes use all my OpenRouter credits on one message?
Hermes hardcodes max_tokens to each model's maximum output (64,000 for Claude models). OpenRouter pre-reserves the full amount as credit collateral before allowing the call. Your $10 balance can't cover a 64K-token reservation even though the actual response would be 50 tokens. Fix: add more credits, or switch to a direct provider that doesn't pre-reserve. Issue #22879 tracks making this configurable.
Does BetterClaw have the same truncation problems?
No. BetterClaw's smart context management handles output limits, context compression, and provider-specific configurations at the platform level. There's no max_tokens to configure, no compression threshold bug, and no credit reservation mismatch. The platform manages the context window so responses complete without truncation. Free tier with 1 agent and BYOK. $19/month per agent for Pro.
