WJb Docs - Intermediate

🛠 Common Issues

This page lists the most frequent problems developers encounter when starting with WJb and how to fix them.

1. Action Not Found

Symptom Job fails with an error that the action cannot be created or resolved.

Cause The action was never registered.

Solution

var wjb = WJbBuilder.Create(store, cfg =>
{
    cfg.AddAction<SendEmailAction>();
    // or
    cfg.AddAction<SendEmailAction>("send-email");
});

Make sure the name used in EnqueueAsync matches the registered name or [ActionName].

2. Payload Cannot Be Converted

Symptom Exception during input binding (JSON deserialization error).

Cause The payload shape does not match the action’s input type.

Solution

• Check property names and types
• Prefer strongly typed models
• Avoid anonymous objects for complex data when possible

3. Workflow Stops Unexpectedly

Symptom Only the first action runs, nothing continues.

Cause The action returned Complete instead of Next, or an exception was thrown.

Solution Open the action and verify the returned IActionResult:

return await NextAsync<NextAction>(payload);   // continues
return await CompleteAsync();                  // stops

4. Jobs Never Execute

Symptom Jobs stay in Pending forever.

Cause No worker / executor is running.

Solution

await wjb.ExecuteLoopAsync(cancellationToken);
// or start the appropriate Worker (WasmWorker, etc.)

5. Cancellation Does Not Work

Symptom Calling TryCancel has no effect.

Cause The action ignores the CancellationToken.

Solution Always pass and respect the token:

ct.ThrowIfCancellationRequested();
await LongRunningCallAsync(ct);

6. Large Payloads / Out of Memory

Symptom Performance problems or memory pressure.

Cause Large files or collections are stored directly in the job payload.

Solution Store large data in IStorage (or external storage) and pass only a reference (ID) in the payload.

7. Retry Loops Forever or Not Enough

Symptom Job keeps retrying or fails too quickly.

Cause Incorrect JobOptions (missing max attempts or wrong delay).

Solution Review the retry settings supplied when the job was enqueued.

8. Side Effects on Retry

Symptom Duplicate emails, double charges, etc.

Cause Action is not idempotent and was retried.

Solution Design actions to be safe when executed more than once, or use explicit checks before performing irreversible work.

Quick Debugging Checklist

1. Is the action registered? 2. Is a worker running? 3. Does the action return Next or Complete as expected? 4. Is the payload shape correct? 5. Does the action respect CancellationToken? 6. Check the job status, result and error in the store.

Key Point

Most issues come from missing registration, missing worker, or incorrect return value from the action.

Because WJb is explicit, these problems are usually easy to locate by reading the code and inspecting the job in the store.