DEV Community: Rachel Vectle

your watsonx.ai error isnt a network error, its a missing env var

Rachel Vectle — Thu, 01 Oct 2026 16:58:00 +0000

An agent wired up watsonx.ai credentials from the SDK example repo, ran the script, and got a connection error. It spent the next several steps checking DNS, retrying, and suspecting the network. The actual bug: WATSONX_URL was empty. A missing URL never reads as an auth error. It reads as a network failure.

import os
from dotenv import load_dotenv

load_dotenv()

def require(name):
    val = os.environ.get(name)
    if not val:
        raise RuntimeError(f"missing required env var: {name}")
    return val

api_key = require("IBM_CLOUD_API_KEY")
url = require("IBM_CLOUD_URL")
project_id = require("IBM_CLOUD_PROJECT_ID")

from ibm_watsonx_ai import Credentials
from ibm_watsonx_ai.foundation_models import ModelInference

creds = Credentials(url=url, api_key=api_key)
model = ModelInference(model_id=model_id, credentials=creds, project_id=project_id)

That's gotcha one. Gotcha two showed up in the same session: the example repo pins ibm/granite-13b-instruct-v2 as the model id. Older granite variants retire, so copying the id from sample code buys you a second cryptic failure a month later. Always list the live model ids for your region.

The pattern worth stealing: validate the three env vars up front and raise a clear error when one is empty. Every agent that talks to a config-heavy API should do this before the first call, because the API itself will never tell you "you forgot a variable." It will tell you the network is broken.

Full skill with the verified fix: https://vectle.com/skills/skl_0lojz_UxrjvMzyHCwPeTzQ

Your DeepInfra baseURL is wrong: it needs /v1/openai, not /v1

Rachel Vectle — Wed, 30 Sep 2026 17:18:56 +0000

Every request 404s and your API key is fine. Your baseURL is the bug.

// wrong: this is what the muscle memory gets you
const client = createOpenAICompatible({
  baseURL: "https://api.deepinfra.com/v1", // 404 on every request
});

// right
const client = createOpenAICompatible({
  baseURL: "https://api.deepinfra.com/v1/openai",
});

createOpenAICompatible appends /chat/completions to whatever baseURL you hand it. DeepInfra serves its OpenAI-compatible API at /v1/openai/chat/completions, not /v1/chat/completions. So baseURL /v1 builds /v1/chat/completions, which does not exist, and every request dies. The fix is one path segment.

Two more things from the provider docs while you are here:

Model ids are HuggingFace-style paths: deepseek-ai/DeepSeek-V4-Flash, meta-llama/Meta-Llama-3.1-8B-Instruct. Not the short names you would guess.
Responses carry usage.estimated_cost. Read it off each response for billing reconciliation instead of estimating from your own token counts.

This is the class of bug agents hit hardest: everything says OpenAI-compatible, the key is valid, and requests 404. The name says compatible. The path says otherwise.

Full skill: https://vectle.com/skills/skl_0hAQafQeJk2cXpMYQ9FNIg

document.parse.completed does not mean the parse succeeded (Affinda webhook gotcha)

Rachel Vectle — Tue, 29 Sep 2026 17:01:10 +0000

Your Affinda webhook handler is processing failed parses as successes. The event name is lying to you.

// this looks fine. it is not.
app.post('/webhooks/affinda', (req, res) => {
  if (req.body.event === 'document.parse.completed') {
    saveToDatabase(req.body.data); // failed parses land here too
  }
});

Affinda's document.parse.completed fires when parsing finishes. Finishes includes fails. A document that Affinda could not parse at all still sends you a completed event, with garbage or missing data attached.

The fix is one check:

app.post('/webhooks/affinda', (req, res) => {
  if (req.body.event !== 'document.parse.completed') return;
  if (req.body.data.failed) {
    handleFailure(req.body.data); // retry, flag, move on
    return;
  }
  saveToDatabase(req.body.data);
});

Or skip the ambiguity entirely and subscribe to document.parse.succeeded and document.parse.failed as separate events. Then your handler never has to ask what completed meant.

This is the kind of bug that survives code review because everyone reads the event name and nods. The docs say completed. Completed sounds done-and-good. It is not. It is done-and-maybe-good.

If you are building agents that wire up third-party webhooks, this pattern repeats across APIs: the event name describes the lifecycle stage, not the outcome. Agents are especially prone to it because they take names at face value.

Full skill with the gotcha list: https://vectle.com/skills/skl_0HecrGUcurc8PVGuJu1dzA