What's the best way to handle an INVALID_CHAT_HISTORY exception?

[khteh]

Checked other resources

• This is a bug, not a usage question. For questions, please use GitHub Discussions.
• I added a clear and detailed title that summarizes the issue.
• I read what a minimal reproducible example is (https://stackoverflow.com/help/minimal-reproducible-example).
• I included a self-contained, minimal example that demonstrates the issue INCLUDING all the relevant imports. The code run AS IS to reproduce the issue.

Example Code

async for step in current_app.agent.astream(
            {"messages": [{"role": "user", "content": user_input['message']}]},
            stream_mode="values", # Use this to stream all values in the state after each step.
            config = config, # This is needed by Checkpointer
        ):
            step["messages"][-1].pretty_print()

Error Message and Stack Trace (if applicable)

2025-04-16 13:32:06 ERROR    /invoke exception! Found AIMessages with tool_calls that do not have a corresponding ToolMessage. Here are the first few of those tool calls: [{'name': 'HealthcareCypher', 'args': {'query': 'Which physician has treated the most patients covered by Cigna?'}, 'id': '930c507b-3c80-4d92-a960-ce5d669aea78', 'type': 'tool_call'}].

Every tool call (LLM requesting to call a tool) in the message history MUST have a corresponding ToolMessage (result of a tool invocation to return to the LLM) - this is required by most LLM providers.
For troubleshooting, visit: https://python.langchain.com/docs/troubleshooting/errors/INVALID_CHAT_HISTORY
Traceback (most recent call last):
  File "/usr/src/Python/rag-agent/src/controllers/HomeController.py", line 138, in invoke
    async for step in current_app.agent.astream(
  File "/home/khteh/.local/share/virtualenvs/rag-agent-YeW3dxEa/lib/python3.12/site-packages/langgraph/pregel/__init__.py", line 2651, in astream
    async for _ in runner.atick(
  File "/home/khteh/.local/share/virtualenvs/rag-agent-YeW3dxEa/lib/python3.12/site-packages/langgraph/prebuilt/chat_agent_executor.py", line 762, in acall_model
    state = _get_model_input_state(state)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/khteh/.local/share/virtualenvs/rag-agent-YeW3dxEa/lib/python3.12/site-packages/langgraph/prebuilt/chat_agent_executor.py", line 733, in _get_model_input_state
    _validate_chat_history(messages)
  File "/home/khteh/.local/share/virtualenvs/rag-agent-YeW3dxEa/lib/python3.12/site-packages/langgraph/prebuilt/chat_agent_executor.py", line 260, in _validate_chat_history
    raise ValueError(error_message)
ValueError: Found AIMessages with tool_calls that do not have a corresponding ToolMessage. Here are the first few of those tool calls: [{'name': 'HealthcareCypher', 'args': {'query': 'Which physician has treated the most patients covered by Cigna?'}, 'id': '930c507b-3c80-4d92-a960-ce5d669aea78', 'type': 'tool_call'}].

Every tool call (LLM requesting to call a tool) in the message history MUST have a corresponding ToolMessage (result of a tool invocation to return to the LLM) - this is required by most LLM providers.
For troubleshooting, visit: https://python.langchain.com/docs/troubleshooting/errors/INVALID_CHAT_HISTORY

Description

This could be due to previous run crashed or user terminated the session abruptly by, say, CTRL-C.

(1) Why did the library persist inconsistent data into the database?
(2) How to recover from this?

Does this refer to the checkpoint DB in PostgreSQL? Which table? Any documentation on the tables? What do they persist and what functionality they provide?

I also notice that there is no timestamp column in all of the checkpoint DB tables. How do we SELECT and ORDER BY the table data?

System Info

System Information
------------------
> OS:  Linux
> OS Version:  #21-Ubuntu SMP PREEMPT_DYNAMIC Wed Feb 19 16:50:40 UTC 2025
> Python Version:  3.12.7 (main, Feb  4 2025, 14:46:03) [GCC 14.2.0]

Package Information
-------------------
> langchain_core: 0.3.51
> langchain: 0.3.23
> langchain_community: 0.3.21
> langsmith: 0.3.27
> langchain_chroma: 0.2.2
> langchain_cli: 0.0.36
> langchain_google_genai: 2.1.2
> langchain_google_vertexai: 2.0.9
> langchain_neo4j: 0.4.0
> langchain_nomic: 0.1.4
> langchain_ollama: 0.3.1
> langchain_openai: 0.3.12
> langchain_text_splitters: 0.3.8
> langgraph_sdk: 0.1.61
> langserve: 0.3.1

Other Dependencies
------------------
> aiohttp<4.0.0,>=3.8.3: Installed. No version info available.
> anthropic[vertexai]: Installed. No version info available.
> async-timeout<5.0.0,>=4.0.0;: Installed. No version info available.
> chromadb!=0.5.10,!=0.5.11,!=0.5.12,!=0.5.4,!=0.5.5,!=0.5.7,!=0.5.9,<0.7.0,>=0.4.0: Installed. No version info available.
> dataclasses-json<0.7,>=0.5.7: Installed. No version info available.
> fastapi: 0.115.9
> filetype: 1.2.0
> gitpython<4,>=3: Installed. No version info available.
> google-ai-generativelanguage: 0.6.17
> google-cloud-aiplatform: 1.71.1
> google-cloud-storage: 2.19.0
> gritql<1.0.0,>=0.2.0: Installed. No version info available.
> httpx: 0.27.2
> httpx-sse: 0.4.0
> httpx-sse<1.0.0,>=0.4.0: Installed. No version info available.
> jsonpatch<2.0,>=1.33: Installed. No version info available.
> langchain-anthropic;: Installed. No version info available.
> langchain-aws;: Installed. No version info available.
> langchain-azure-ai;: Installed. No version info available.
> langchain-cohere;: Installed. No version info available.
> langchain-community;: Installed. No version info available.
> langchain-core!=0.3.0,!=0.3.1,!=0.3.10,!=0.3.11,!=0.3.12,!=0.3.13,!=0.3.14,!=0.3.2,!=0.3.3,!=0.3.4,!=0.3.5,!=0.3.6,!=0.3.7,!=0.3.8,!=0.3.9,<0.4.0,>=0.2.43: Installed. No version info available.
> langchain-core<1.0.0,>=0.3.49: Installed. No version info available.
> langchain-core<1.0.0,>=0.3.51: Installed. No version info available.
> langchain-deepseek;: Installed. No version info available.
> langchain-fireworks;: Installed. No version info available.
> langchain-google-genai;: Installed. No version info available.
> langchain-google-vertexai;: Installed. No version info available.
> langchain-groq;: Installed. No version info available.
> langchain-huggingface;: Installed. No version info available.
> langchain-mistralai: Installed. No version info available.
> langchain-mistralai;: Installed. No version info available.
> langchain-ollama;: Installed. No version info available.
> langchain-openai;: Installed. No version info available.
> langchain-perplexity;: Installed. No version info available.
> langchain-text-splitters<1.0.0,>=0.3.8: Installed. No version info available.
> langchain-together;: Installed. No version info available.
> langchain-xai;: Installed. No version info available.
> langchain<1.0.0,>=0.3.23: Installed. No version info available.
> langserve[all]>=0.0.51: Installed. No version info available.
> langsmith-pyo3: Installed. No version info available.
> langsmith<0.4,>=0.1.125: Installed. No version info available.
> langsmith<0.4,>=0.1.17: Installed. No version info available.
> neo4j: 5.28.1
> neo4j-graphrag: 1.6.1
> nomic: 3.4.1
> numpy<2.0.0,>=1.22.4;: Installed. No version info available.
> numpy<2.0.0,>=1.26.2;: Installed. No version info available.
> numpy<3,>=1.26.2: Installed. No version info available.
> ollama<1,>=0.4.4: Installed. No version info available.
> openai-agents: Installed. No version info available.
> openai<2.0.0,>=1.68.2: Installed. No version info available.
> opentelemetry-api: 1.31.1
> opentelemetry-exporter-otlp-proto-http: Installed. No version info available.
> opentelemetry-sdk: 1.31.1
> orjson: 3.10.16
> packaging: 24.2
> packaging<25,>=23.2: Installed. No version info available.
> pillow: 10.4.0
> pydantic: 2.9.2
> pydantic-settings<3.0.0,>=2.4.0: Installed. No version info available.
> pydantic<3.0.0,>=2.5.2;: Installed. No version info available.
> pydantic<3.0.0,>=2.7.4: Installed. No version info available.
> pydantic<3.0.0,>=2.7.4;: Installed. No version info available.
> pytest: 8.3.5
> PyYAML>=5.3: Installed. No version info available.
> requests: 2.32.3
> requests-toolbelt: 1.0.0
> requests<3,>=2: Installed. No version info available.
> rich: 14.0.0
> SQLAlchemy<3,>=1.4: Installed. No version info available.
> sse-starlette: 1.8.2
> tenacity!=8.4.0,<10,>=8.1.0: Installed. No version info available.
> tenacity!=8.4.0,<10.0.0,>=8.1.0: Installed. No version info available.
> tiktoken<1,>=0.7: Installed. No version info available.
> tomlkit>=0.12: Installed. No version info available.
> typer[all]<1.0.0,>=0.9.0: Installed. No version info available.
> typing-extensions>=4.7: Installed. No version info available.
> uvicorn<1.0,>=0.23: Installed. No version info available.
> zstandard: 0.23.0

[hinthornw]

This is not a bug with LangGraph and is a duplicate of previous discussions. Transferring to discussions.

[hinthornw]

To your question.

(1) Why did the library persist inconsistent data into the database?
The library checkpoints after every superstep. If you have a list of messages at the end of step 1, and it fails in step 2, and you resume, you get the state at the end of step 1.
(2) How to recover from this?
Remove the invalid message using something like RemoveMessage or handle it in your LLM call.

[khteh]

How do I know what to remove?

[khteh]

I found this https://langchain-ai.github.io/langgraph/how-tos/memory/delete-messages/#programmatically-deleting-messages but here are the challenges:

(1) I am using ReAct agent. This looks like a housekeeping task. Would adding this as a @tool work?

(2) The error is caught in exception. Would using a decorator with retry logic to clean up the erraneous AIMessage without ToolMessage work?

[khteh]

https://langchain-ai.github.io/langgraph/troubleshooting/errors/INVALID_CHAT_HISTORY/

Which of the variants of "config" (langchain-ai/langchain#30871) is the config input parameter to aget_state? Why can't it just use the existing config it has with the StateGraph?

[khteh]

Can someone review if this is the right and optimized way of doing it? It seems to work for me:

except Exception as e:
    # https://langchain-ai.github.io/langgraph/troubleshooting/errors/INVALID_CHAT_HISTORY/
    logging.exception(f"/invoke exception! {str(e)}, repr: {repr(e)}")
    if attempt == 2:
        raise HTTPException(description = str(e))
    if "Found AIMessages with tool_calls that do not have a corresponding ToolMessage" in str(e):
        # state = await current_app.agent.with_config(config).aget_state() XXX: This doesn't work! Why?
        state = await current_app.agent.aget_state({"configurable": {"thread_id": session["thread_id"], "user_id": session["user_id"]}})
        tool_messages = set()
        outstanding_tool_call_ids = set()
        # Assumption: state.messages is chronologically ordered
        for message in reversed(state.values["messages"]):
            msg = ChatMessage.from_langchain(message)
            if msg.type == "tool":
                tool_messages.add(msg.tool_call_id)
            elif msg.type == "ai" and len(msg.tool_calls):
                for tc in msg.tool_calls:
                    if tc["id"] not in tool_messages:
                        outstanding_tool_call_ids.add(tc["id"])
        for id in outstanding_tool_call_ids:
            await current_app.agent.with_config(config).ainvoke({'messages': [ToolMessage(content="Whatever!", tool_call_id=id)]})