Atlas fails with "Compaction parent must be a user message: <parentID>" because session compaction anchors the compacted history on a user message, and the parentID you supplied resolved to an assistant message instead. The fix is to anchor compaction on a user message id, not an assistant one, or to let Atlas pick the parent automatically instead of passing one explicitly. A session that contains no user message at all cannot be compacted.
Why does Atlas report "Compaction parent must be a user message"
Atlas reports "Compaction parent must be a user message: <parentID>" for exactly 1 reason: the parentID handed to compaction resolved to an assistant message. Atlas session compaction anchors the compacted history on a user message, so an assistant anchor is rejected outright.
Compaction in Atlas rewrites a long session into a shorter transcript that the model can still reason over. The compacted history has to hang off a coherent starting point, and Atlas uses a user message as that anchor. If compaction accepted an assistant message as the parent, the resulting transcript would begin mid-turn, with a model reply that answers a question no longer present in the history. Rather than emit that incoherent transcript, Atlas refuses and names the offending id in the error. The message is a guard, not a bug: the parentID you passed simply points at the wrong kind of message.
How to fix the Atlas compaction parent error
Fixing the Atlas compaction parent error takes 1 change: pass a user message id as the compaction parent instead of an assistant message id. If you are driving compaction through the API, re-read the transcript and pick the nearest preceding user message before retrying.
Walk the session transcript backward from the id you originally passed until you reach a user message, and use that id as the parent. The nearest preceding user message is almost always the anchor you actually wanted, because it is the turn that started the exchange the assistant message belongs to. Once the parent is a user message, compaction proceeds normally. Be honest about the caveat: correcting the id fixes the refusal, but it does not change what compaction summarizes away, so re-check that the anchor you chose is the point in the conversation you genuinely want to keep.
How to let Atlas pick the compaction parent automatically
The simplest fix for the Atlas "Compaction parent must be a user message" error is to stop passing a parent at all. Atlas will pick the parent automatically when you do not supply one explicitly, which removes the entire class of assistant-anchored parentID mistakes in 1 step.
Explicit parent selection is useful when you want to compact from a specific point in a session, but most callers do not need it. Omitting the parentID lets Atlas choose an anchor that already satisfies the user-message rule, so the error cannot occur. Reach for an explicit parentID only when you have a concrete reason to compact from a chosen turn, and when you do, validate the message role before you send it. Automatic selection is the recommended default for scripts and integrations that compact sessions on a schedule.
How to verify the compaction fix worked
Verify the Atlas compaction fix by re-running compaction on the same session after switching the parentID to a user message id. Success means 1 thing: the Compaction parent must be a user message error is gone, and the session compacts without the parentID guard firing again.
Re-run the compaction call with the corrected anchor and watch for the absence of the error string. If the same message reappears with a different parentID in the angle brackets, the new id also resolved to an assistant message, so walk further back in the transcript. If compaction still refuses and the session genuinely contains no user message, that session cannot be compacted at all, which is the documented limit rather than a failure you can configure around. Start a new session in that case and carry the work forward.
When a session cannot be compacted at all
An Atlas session that contains 0 user messages cannot be compacted at all. Atlas compaction anchors the compacted history on a user message, so a transcript with zero user turns offers no valid anchor, and retrying with a different parentID will never succeed for that session.
The uncompactable case is rare but real, and it is worth recognizing quickly instead of retrying in a loop. If you have already walked the transcript and confirmed there is no user message to anchor on, no parentID value will satisfy the check. Atlas is a terminal-native AI coding agent that fans out work to subagents which can run in the foreground or in parallel background sessions, and machine-driven sessions are the ones most likely to lack a user turn. Treat those sessions as short-lived and let them end rather than trying to compact them.
How to fix it
- 01Anchor compaction on a user message id, not an assistant one.
- 02If you are driving compaction through the API, re-read the transcript and pick the nearest preceding user message.
- 03Let Atlas pick the parent automatically instead of passing one explicitly.
- 04Retry compaction; a session with no user message at all cannot be compacted.
Frequently asked questions
- What does "Compaction parent must be a user message" mean in Atlas?
- The error means the parentID you passed to Atlas session compaction resolved to an assistant message. Atlas anchors compacted history on a user message, so it refuses an assistant anchor rather than producing an incoherent transcript.
- How do I fix the Atlas compaction parentID error?
- Pass a user message id as the compaction parent instead of an assistant message id. If you drive compaction through the API, re-read the transcript and pick the nearest preceding user message, then retry.
- Can I let Atlas choose the compaction parent for me?
- Yes. Let Atlas pick the parent automatically instead of passing one explicitly. Omitting the parentID avoids the assistant-message anchor problem entirely and is the safest default for scripts.
- Why does Atlas refuse to compact from an assistant message?
- Atlas compaction anchors the compacted history on a user message. Anchoring on an assistant message would produce an incoherent transcript that begins with a reply to a question no longer in the history, so Atlas refuses instead.
- Is the Atlas compaction parent error a bug?
- No. The check is a deliberate guard in Atlas session compaction. It fires when the supplied parentID resolves to an assistant message, and the fix is to supply a user message id or to let Atlas select the parent.
- What if my Atlas session has no user message at all?
- A session with no user message cannot be compacted at all. No parentID will satisfy the anchor rule, so stop retrying, and start a fresh session instead of trying to compact that one.
- Which user message should I use as the compaction parent in Atlas?
- Use the nearest preceding user message relative to the id you originally passed. Walk the Atlas transcript backward from the rejected assistant message until you reach a user turn, then use that message id.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas with DeepSeek-V3.1 671B (Ollama): Self-Hosting Frontier Open Weights in 2026
DeepSeek-V3.1 671B (Ollama) is a 404GB MoE with a 160K context and hybrid thinking modes. Run Atlas on frontier open weights behind your own firewall in 2026.
Atlas with Llama 3.3 8B Instruct (Meta Llama API): The small_model Slot in 2026
Llama 3.3 8B Instruct (Meta Llama API) in Atlas for 2026: 128,000 tokens of context in an 8B-class model, a 4,096 token output cap, and why it belongs in small_model.
Atlas with GitHub Models in 2026: Free Model Access Behind a GITHUB_TOKEN
Run Atlas on GitHub Models in 2026: every model listed at $0/$0 per Mtok, auth with the GITHUB_TOKEN you already have, and 256,000 tokens on AI21 Jamba 1.5 Large.
Atlas with Qwen2.5-Coder 7B (local via Ollama): the Laptop Setup in 2026
Qwen2.5-Coder 7B runs Atlas on a laptop with no discrete GPU: about 5GB at 4-bit, a 32,768 token context, and free self-hosted. Setup, limits, and when to upgrade.
Atlas for JavaScript in 2026
In 2026, Atlas empowers JavaScript developers with a terminal-native AI coding agent. It indexes code by AST, uses local embeddings, and offers permission-gated tools for safe, efficient development.
Atlas with Llama 3.1 8B (local via Ollama): The 4.9GB Baseline for 2026
Llama 3.1 8B (local via Ollama) in Atlas for 2026: a 4.9GB pull that fits 8GB of VRAM, Free (self-hosted), and honest limits on a general-purpose 8B model.
Atlas with Qwen3.7 Max: Alibaba's May 2026 Frontier Tier at $2.50 / $7.50
Qwen3.7 Max in Atlas: Alibaba's May 2026 flagship, a 1M context model at $2.50 / $7.50 per Mtok, or $1.25 / $3.75 through Together. Setup with DASHSCOPE_API_KEY.
Atlas with Qwen Flash: A Cheap Tier That Still Writes Real Diffs in 2026
Run Atlas on Qwen Flash in 2026. Alibaba's fast tier pairs 1M tokens (1,000,000) of context with a 32,768 token output at $0.05 per Mtok in, $0.40 per Mtok out.