Regression: ExaClient (@agentic/exa >= 7.6.3) Causes Timeouts in Docker Environment (Node 18 Alpine / DigitalOcean)

[steveoon]

Hi Team,

I've encountered a regression issue with @agentic/exa (and potentially related @agentic/* packages) starting from version ^7.6.3. Calls using ExaClient consistently time out when the application is deployed within a specific Docker environment, whereas they worked perfectly fine with version 7.3.3.

Bug Description:

When using a tool that utilizes ExaClient.search() and potentially ExaClient.getContents() (like a web search tool), the operation times out after upgrading @agentic/exa and related @agentic/* packages from version 7.3.3 to ^7.6.3.

• Working Scenario: With all @agentic/* packages at version 7.3.3, the tool executes successfully within the Docker container deployed on DigitalOcean.
• Failing Scenario: After upgrading the @agentic/* packages to ^7.6.3 (or the latest resolved version), the exact same tool code deployed in the exact same environment consistently results in a timeout during the ExaClient operation.
• The tool works correctly with the newer versions (^7.6.3) when deployed locally or on Vercel. The issue seems specific to the Docker/DigitalOcean environment combination after the library upgrade.

Environment:

• @agentic/exa Failing Version: ^7.6.3 (and related @agentic/* packages)
• @agentic/exa Working Version: 7.3.3 (and related @agentic/* packages)
• Node.js Version: 18 (specifically node:18-alpine Docker base image)
• Deployment Environment: Docker container running on DigitalOcean Droplet (1vCPU / 1GB RAM)
• Operating System (Host): Ubuntu (assumed, typical for DO)
• Reverse Proxy: Nginx (Configuration reviewed, seems unlikely to be the cause)

Steps to Reproduce:

1. Create a Next.js application using @agentic/[email protected]. Include a tool that makes calls to ExaClient.search() and/or ExaClient.getContents().
2. Build a Docker image using node:18-alpine as the base.
3. Deploy the container to a DigitalOcean Droplet (or similar resource-constrained Linux environment). Ensure the EXA_API_KEY environment variable is correctly passed to the container.
4. Trigger the tool -> Expected: It should work.
5. Update @agentic/* packages in package.json to ^7.6.3.
6. Rebuild the Docker image and redeploy to the same environment.
7. Trigger the tool -> Actual: The ExaClient operation times out.

Troubleshooting Steps Taken:

• Confirmed network connectivity from within the Docker container to api.exa.ai using node -e "fetch(...)". Direct fetch calls (using the correct x-api-key header and EXA_API_KEY env var) succeed with a 200 status code, even within the failing container.
• Verified DNS resolution within the container works for api.exa.ai.
• Confirmed the EXA_API_KEY environment variable is correctly set and accessible within the container using process.env.
• Reviewed Nginx configuration; it doesn't seem related as it handles inbound traffic.
• Reviewed DigitalOcean firewall rules; outbound TCP traffic on all ports is allowed.
• Implemented explicit timeouts (Promise.race with setTimeout) around the ExaClient calls, which confirmed the operation is indeed hanging until the timeout triggers.
• Isolated the issue specifically to the upgrade of the @agentic/* packages by checking out a previous commit where version 7.3.3 was used (which worked correctly in the same Docker environment).

Expected Behavior:

The ExaClient operations (search, getContents) should complete successfully within the Docker environment using version ^7.6.3, just as they did with 7.3.3 and as they do in other deployment environments (local/Vercel).

Actual Behavior:

The ExaClient operations hang indefinitely until an implemented application-level timeout is reached when using version ^7.6.3 in the specified Docker environment.

Possible Cause:

It seems likely that a change introduced between 7.3.3 and ^7.6.3 in @agentic/exa or its dependencies interacts negatively with the specific Docker (node:18-alpine) or networking environment on DigitalOcean, despite basic network connectivity being functional (as proven by direct fetch tests). This could relate to internal handling of HTTP requests, connection pooling, timeouts, TLS, or dependencies within the library.

Workaround:

Pinning @agentic/* packages to version 7.3.3 resolves the issue for now.

[stevepeak]

Hi @steveoon thank you for expressing this issue and with such thorough detail ❤️ I'll be helping this project out, but just getting ramped up. Here just leaving a comment that I hear you and will return shortly to address this issue fully 🙏