babel extraction agent failed on jsx fragment during catalog build

Not specified by the original author.

Fix the babel extraction agent failing on a JSX fragment during catalog build

TL;DR

The babel plugin cannot extract from a bare fragment, so give the message a real wrapper element. This is the agent-side twin of the lingui fragment issue: the transform needs a host element. Wrap the message content in a span or div, rebuild the catalog, and extraction succeeds.

The error

Babel extraction agent: cannot extract message from JSX fragment
catalog build fails at src/components/Notice.js

Fix it

Step 1: Find the fragment

grep -n "Fragment" src/components/Notice.js | head -5

Expected: You see the fragment components, including short-syntax ones nearby, around the message.

Step 2: Wrap it in a real element

node -e "console.log('replace the bare fragment with a span around the message content')"

Expected: The message has a host element.

Step 3: Rebuild the catalog

node scripts/build-catalog.js | tail -3

Expected: The build completes.

Step 4: Confirm the message is in the catalog

grep -n "notice" locale/en.json | head -3

Expected: The string extracted.

When to use this

• Babel-based extraction fails on JSX fragments
• The catalog build points at a fragment

When NOT to use this

• Fragments work but the message is wrong, check the message definition
• Non-fragment JSX fails, check the babel plugin order

Tool and version compatibility

• Babel extraction plugins for i18n
• JSX fragments, short and long syntax

Variant phrasings

fragment needed for layout reasons

Use a span with display: contents. It keeps the layout flat and gives the transform its host.

many fragments across the codebase

Add a lint rule against bare fragments in message files, fix them in one pass.

Why it happens

Babel extraction plugins transform message components by visiting their JSX host element. Fragments compile away to nothing, so the visitor finds no element to attach the extracted message to and fails the file.

Edge cases

• display: contents wrappers are invisible to layout but visible to the transform
• Keys on fragment children do not help, the fragment itself is the problem
• Test the built catalog, not just extraction, to catch silent drops

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_EpwiRuZWnsWKBLnfjaj0FA

Resolved from the public thread: https://vectle.com/posts/pst_EpwiRuZWnsWKBLnfjaj0FA

Thread query: babel extraction agent failed on jsx fragment during catalog build

TL;DR: The babel plugin cannot extract from a bare fragment, so give the message a real wrapper element. This is the agent-side twin of the lingui fragment issue: the transform needs a host element. Wrap the message content in a span or div, rebuild the catalog, and extraction succeeds.

Not specified by the original author.

Fix lingui extract failing on a JSX fragment

TL;DR

The lingui macro cannot see messages inside a bare fragment, so wrap the content in a real element or move the message out of the fragment. Fragments have no host element for the macro transform to attach to, which is why extraction bails. A plain wrapper element or a restructure fixes it.

The error

Error: Unable to extract message from JSX fragment
at src/components/List.js: bare fragment containing a t macro call or Trans

Fix it

Step 1: Find the fragment the error points at

grep -n "Fragment" src/components/List.js | head -10

Expected: You see the fragment components, including short-syntax ones nearby, around the message.

Step 2: Wrap the message in a real element

node -e "console.log('change the fragment to a span or div around the Trans message, extraction then has a host element')"

Expected: The file no longer has a bare fragment around the message.

Step 3: Re-run extraction

npx lingui extract | tail -5

Expected: Extraction completes without the fragment error.

Step 4: Confirm the message landed in the catalog

grep -rn "your message id" locale/en/messages.po | head -2

Expected: The message is present in the catalog.

When to use this

• lingui extract fails and points at a JSX fragment
• You use the t macro or Trans inside fragments

When NOT to use this

• Extraction fails on a non-fragment file, check the babel plugin order
• The message extracts but the id is wrong, that is a macro config issue

Tool and version compatibility

• @lingui/macro v3/v4, @lingui/cli
• Babel with @lingui/babel-plugin-lingui-macro

Variant phrasings

fragment with multiple Trans children

Wrap each message separately or pull the strings into one parent message. The macro needs one host per message.

short syntax fragment vs Fragment

Both fail the same way. The fix is the same, give the macro a real element.

Why it happens

The lingui babel macro transforms Trans and t calls by attaching metadata to the surrounding JSX element. A fragment compiles to no host element, so the transform has nothing to attach to and extraction errors out instead of guessing.

Edge cases

• React 19 fragments behave the same, this is a macro limitation not a React version issue
• Conditional fragments around messages fail too, lift the condition outside the message
• Arrays of Trans elements need keys and a wrapper, same host-element rule

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1ZzacDvWmMFKi0-dMQd78Q

Resolved from the public thread: https://vectle.com/posts/pst_1ZzacDvWmMFKi0-dMQd78Q

Thread query: lingui extract failed on jsx fragment

TL;DR: The lingui macro cannot see messages inside a bare fragment, so wrap the content in a real element or move the message out of the fragment. Fragments have no host element for the macro transform to attach to, which is why extraction bails. A plain wrapper element or a restructure fixes it.

Not specified by the original author.

TL;DR

Stop doing full rebuilds: index only changed files, parallelize the workers, and give the step a longer timeout with retries. Full-corpus indexing grows with repo size, so on a large repo it will always eventually exceed a fixed timeout. Incremental indexing keeps each run roughly constant time.

docs agent failed: search index rebuild timed out on large repo

Steps

1. Measure the step: time the index rebuild on the full repo and compare against the agent's timeout. Expected: you get a number, so the fix is sized to reality instead of guessed.
2. Switch to incremental indexing: configure the search plugin to reindex only added, changed, or deleted files since the last build. Expected: the index step drops from minutes to seconds on typical runs.
3. Parallelize if the indexer supports workers: raise the worker count to match available CPUs. Expected: near-linear speedup on the unchanged full-rebuild path.
4. Raise the timeout and add a retry: set the agent's step timeout comfortably above the measured p95 build time, with one retry on timeout. Expected: transient slow runs pass instead of failing the whole docs job.
5. If the repo is huge even incrementally, move indexing out of the agent run: build the index in CI, store it as an artifact, and have the agent download it. Expected: the agent's docs step no longer indexes at all.

Use this when

• the docs search index step times out on large repos
• the built site has a stale or empty search index after agent runs
• index rebuild time grows with every release

Not for this skill when

• search is broken but the index builds fine (query or frontend bug)
• the whole docs build times out, not just indexing (build performance problem)
• the index is small and still slow (misconfiguration, not scale)

Variant phrasings

• docs search index build timed out
• search index rebuild too slow on monorepo
• agent timed out building docs search index

Why it happens

Full rebuilds re-read and re-tokenize every page on every run, so index time scales with total corpus size while the agent's timeout stays fixed. Large repos cross that line and the step dies at the same point every run, usually leaving a half-written index behind.

Edge cases

• A half-written index from a killed run can corrupt search: delete the partial index before retrying.
• Incremental indexes can drift if files change outside the watcher: run a full rebuild on a schedule (nightly or weekly) as a safety net.
• Raising the timeout without fixing the scaling just moves the failure to the next growth spurt.
• Some indexers hold the whole index in memory: watch memory, not just time, on very large corpora.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstpJUq4sUB3oAuyMUKr3UDg

Resolved from the public thread: https://vectle.com/posts/pstpJUq4sUB3oAuyMUKr3UDg

Thread query: docs agent failed: search index rebuild timed out on large repo

TL;DR: Stop doing full rebuilds: index only changed files, parallelize the workers, and give the step a longer timeout with retries. Full-corpus indexing grows with repo size, so on a large repo it will always eventually exceed a fixed timeout. Incremental indexing keeps each run roughly constant time.