Language Server Error "invalid AST" (IEP-1783)

[tiwag]

Describe the bug
After building the project a Language Server Error "invalid AST" occurs
and in the Outline View all items disappear (nothing shown anymore)

To Reproduce
Steps to reproduce the behavior:

1. Add a new Espressif IDE project from template "i2c_tools"
2. build the project
3. open definition of field ival (cmd_i2ctools.c line 39)
4. errors occur during parsing of argtable3.h

Screenshots

Bug Report

bug_report_20260602_085832.zip

languageServers-log.zip

project
i2c_tools.zip

[github-actions]

Hi @tiwag! This is an automated response.
If you don’t find the answer helpful, please check the ESP32 IDE forum (https://www.esp32.com/viewforum.php?f=40) or GitHub issues (https://github.com/espressif/idf-eclipse-plugin/issues) to see if the issue has already been discussed.

---

Language Server Error "invalid AST" in Espressif-IDE

This issue is related to the LSP/clangd setup in Espressif-IDE 3.0.0+. The "invalid AST" error typically occurs when clangd encounters compiler flags that it doesn't recognize (flags specific to the GCC toolchain used to build ESP-IDF projects).

Likely Cause

When navigating to definitions (like ival in argtable3.h), clangd parses the file using the compilation flags from compile_commands.json. Since Espressif-IDE uses the GCC toolchain by default, some -m* and -f* flags in compile_commands.json are unknown to clangd, causing parsing failures and the "invalid AST" error. [LSP Support Docs]

Recommended Fix

Option 1: Check/create the .clangd configuration file

Ensure a .clangd file exists in your project root with the following content:

CompileFlags:
  CompilationDatabase: build
  Remove: [-m*, -f*]

This removes the GCC-specific flags that clangd doesn't understand. [clangd Setup]

Option 2: Use the fix_compile_commands.py script

If the .clangd config alone doesn't resolve it, you can also use the provided script to clean up compile_commands.json:

1. Download fix_compile_commands.py.
2. Add it as a post-build step in your CMakeLists.txt:

if(EXISTS "${CMAKE_SOURCE_DIR}/fix_compile_commands.py")
    add_custom_target(
        fix_clangd ALL
        COMMAND ${CMAKE_COMMAND} -E echo "Running fix_compile_commands.py..."
        COMMAND ${CMAKE_COMMAND} -E env python3 ${CMAKE_SOURCE_DIR}/fix_compile_commands.py
        COMMENT "Cleaning compile_commands.json for clangd"
        VERBATIM
    )
endif()

3. Rebuild the project — the script will strip the problematic -m* and -f* flags from compile_commands.json. [Unknown Argument Fix]

Additional Check

Make sure the CDT Indexer is disabled (it should be by default in Espressif-IDE 3.0.0+):

1. Go to Window > Preferences > C/C++ > Indexer.
2. Uncheck Enable Indexer and click Apply and Close. [Disable CDT Indexer]

Note: The knowledge sources do not contain a direct explanation of the "invalid AST" error specifically, so the above is based on the documented causes of similar clangd parsing errors in Espressif-IDE. If the issue persists after these steps, consider reporting it with the attached logs on the idf-eclipse-plugin GitHub issues page.

[tiwag]

.clangd file is present

fix_compile_commands doesnt solve the problem

CDT Indexer is disabled

project with fix_compile_commands
i2c_tools_fcc.zip

[dizcza]

Same issue. Refer to #1479 (comment) for details.

[sigmaaa]

Hi @tiwag,

Thank you for reporting this issue.

From the logs, I can see that the issue originates from the tools rather than the IDE. More specifically, this appears to be a toolchain issue: ESP-IDF uses the compiler flag -mtune=esp-base, which is not recognized by this version of clangd.

This issue seems to be target-specific, as I do not observe it with other targets or ESP-IDF versions.

Could you please try the following workaround? It seems to work for me:

Create a config.yaml file in:

C:\Users\**USER_NAME**\AppData\Local\clangd

with the following content:

CompileFlags:
  Remove:
    - "-mtune=esp-base"

After creating the file, restart the IDE and check whether the issue persists.

[tiwag]

Hi @sigmaaa

yes this solved the problem !

brgds tiwag

[tiwag]

in every project directory a

.clangd file is created, which contents

CompileFlags:
  CompilationDatabase: build
  Remove: [-m*, -f*]

shouldn't that too the same ?
doesn't it work ?
is the syntax wrong?

[sigmaaa]

in every project directory a

.clangd file is created, which contents

CompileFlags:
  CompilationDatabase: build
  Remove: [-m*, -f*]

shouldn't that too the same ? doesn't it work ? is the syntax wrong?

.clangd is workspace-wide, but clangd only applies full project context when a file is in the compilation database. Outside of it (e.g. some headers), it falls back to default settings.