agent-troubleshooting

Agent Troubleshooting Guide

Common issues agents encounter when working on XActions and how to resolve them.

---

Tests

Tests fail with "Task not found: undefined"

Cause: TaskStore methods are async — calling store.create() without await returns a Promise, not a task object. Passing the Promise as a task ID fails. Fix: Add await to all store.create(), store.get(), store.transition(), store.list() calls. Make test callbacks async.

Integration test worker crashes / times out

Cause: Usually an infinite pagination loop. scrapeUserList loops while (seen.size < limit). If the mock always returns the same response with a cursor and seen.size never reaches limit, it loops forever. Fix: Use a call counter in the mock. Return a no-cursor response after the first call per endpoint:

let callCount = 0;
const fetchMock = vi.fn(async (url) => {
  if (url.includes('Followers')) {
    callCount++;
    if (callCount > 1) return mockResponse({}); // no cursor → terminates
    return mockResponse(graphqlBody(FOLLOWERS_RESPONSE));
  }
});

x402-integration tests fail with 429 instead of 402

Cause: These tests require a running API server. Without the server, they hit a different endpoint. Fix: Start the server first: npm run dev. Then run: npx vitest run tests/x402-integration.test.js.

Mutation mock returns wrong shape

Cause: For GraphQL queries, client.graphql() wraps the response as { data: json, cursor }. For mutations (mutation: true), it returns the raw JSON directly. Fix: For mutation mocks, pass the full fixture with the data wrapper: mockResponse(TWEET_CREATE_RESPONSE), not mockResponse(graphqlBody(TWEET_CREATE_RESPONSE)).

Media upload test: "Cannot read properties of undefined (reading 'processing_info')"

Cause: MEDIA_FINALIZE_RESPONSE includes processing_info, which triggers a STATUS poll call. The mock has no response for this extra call, so it returns undefined. Fix: Add a STATUS mock after FINALIZE: .mockResolvedValueOnce({}). The pollProcessingStatus function returns immediately when processing_info is absent.