Skip to content

Jobs Troubleshooting

Use this page when a Container Apps Job fails, hangs, misses a schedule, or does not fan out the way you expected.

Symptom

Common symptoms:

  • job fails immediately after starting
  • job runs but never completes
  • event-driven job never triggers
  • scheduled job appears to miss a window
  • replica fan-out does not match expectations
flowchart TD
    A[Job issue observed] --> B{Execution created?}
    B -->|No| C[Inspect trigger type and metadata]
    B -->|Yes| D{Container starts successfully?}
    D -->|No| E[Check image pull, config, startup]
    D -->|Yes| F{Execution finishes?}
    F -->|No| G[Check loops, deadlocks, timeout]
    F -->|Yes but wrong fan-out| H[Check parallelism and completion count]
    C --> I[Re-run and verify]
    E --> I
    G --> I
    H --> I

Possible Causes

Symptom Possible causes
Fails immediately bad image, registry auth, missing env var, startup crash, secret or identity issue
Runs but never completes infinite loop, blocked I/O, no exit path, timeout mismatch
Event-driven job not triggering scaler metadata mismatch, auth failure, unsupported scaler assumption, empty source
Scheduled run missed cron misunderstanding, UTC/local-time confusion, prior long-running execution, external scheduler assumptions
Replica fan-out not working parallelism misunderstood, replicaCompletionCount set too low or too high, workload itself serializes all work

Diagnosis Steps

Job fails immediately

  1. List executions and inspect the failed run.
  2. Check image and registry configuration.
  3. Review console and system logs for startup/auth errors.
az containerapp job execution list \
  --name "$JOB_NAME" \
  --resource-group "$RG" \
  --output table

az containerapp job execution show \
  --name "$JOB_NAME" \
  --resource-group "$RG" \
  --job-execution-name "$EXECUTION_NAME" \
  --output json
Command Why it is used
az containerapp job execution ... Creates, updates, starts, or inspects a Container Apps job.

Job runs but never completes

  1. Compare observed runtime with replicaTimeout.
  2. Look for application logs that show loops or blocked dependencies.
  3. Verify the process exits after successful work.

Event-driven job not triggering

  1. Re-check scaler metadata names and values.
  2. Validate identity or secret access to the event source.
  3. Confirm there is actually backlog or lag to trigger on.

Do not assume Jobs support every app scaler

If you copied scaler configuration from a continuously running Container App, verify that the same scaler is currently supported for event-driven Jobs before you keep debugging metadata.

Scheduled job missed an execution

  1. Translate the cron expression into UTC and local business time.
  2. Compare the expected window with recent execution timestamps.
  3. Check whether the previous run was still active or failed unexpectedly.

Overlap behavior still needs direct verification

This troubleshooting path treats overlap as a possibility you must design around. Confirm current product behavior before you assume the platform will serialize or skip overlapping schedule windows for you.

Replica fan-out not working

  1. Confirm configured parallelism and replicaCompletionCount.
  2. Inspect the workload: it may still process input sequentially inside each replica.
  3. Validate that external dependencies are not enforcing serialization.

Resolution

Symptom Resolution
Fails immediately fix image pull, env vars, secret refs, identity, or startup command
Never completes add explicit exit path, reduce work per execution, raise timeout only after measuring
Event-driven not triggering correct scaler metadata, fix auth, switch to a verified event source if needed
Missed schedule rewrite cron in UTC, widen interval, add external lock or alerting
Fan-out mismatch align parallelism, replicaCompletionCount, and workload partition logic

Prevention

  • emit structured logs with execution correlation fields
  • document cron expressions in UTC and business-local time
  • validate scaler config in a lower environment before production
  • keep retries low until idempotency is proven
  • separate input repair, replay, and dead-letter procedures in the runbook

Prerequisites

Azure CLI, access to the target resource group, and permission to read or update the Container Apps resources described by this page.

When to Use

Use this procedure when the operational symptom or maintenance task matches the scenario described above.

Procedure

Follow the commands and checks in this page in order, recording the before-and-after configuration for the incident or change record.

Verification

Confirm the target app, revision, job, logs, or metric state matches the expected result before closing the task.

Rollback / Troubleshooting

If verification fails, revert only the last configuration change, capture the failing output, and use the linked troubleshooting guide before retrying.

See Also

Sources