Unassigned Reasons

Overview

When the VRP solver cannot assign certain jobs to any resource, it can now provide detailed reasons explaining why each job remains unassigned. This feature helps identify scheduling conflicts and constraints preventing job assignments.

Enabling Unassigned Reasons

To receive unassigned reasons in your response, enable the explanation feature with the onlyUnassigned option:

{
  "options": {
    "explanation": {
      "enabled": true,
      "onlyUnassigned": true
    }
  }
}

Example Request

Here’s an example where jobs cannot be assigned due to time window conflicts:

{
 "resources": [
    {
      "name": "R-1",
      "start": {
        "latitude": 50.9712020025867901,
        "longitude": 3.86665669380
      },
      "shifts": [
        {
          "from": "2023-01-13T08:00:00Z",
          "to": "2023-01-13T17:00:00Z"
        }
      ]
    }
  ],
  "jobs": [
    {
      "name": "J-1",
      "location": {
        "latitude": 50.98178504860948,
        "longitude": 3.5914227684018565
      },
      "duration": 3456
    },
    {
      "name": "J-2",
      "location": {
        "latitude": 51.088727780102886,
        "longitude": 3.695412188048855
      },
      "duration": 3090
    }
  ],
  "options": {
    "partialPlanning": true,
    "explanation": {
      "enabled": true,
      "onlyUnassigned": true
    }
  }
}

Example Response

The response includes an unservedReasons map that explains why each unassigned job could not be scheduled:

{
  "trips": [
    {
      "resource": "worker1",
      "visits": [
        {
          "job": "job2"
        }
      ]
    }
  ],
  "unserved": ["job1"],
  "unservedReasons": {
    "job1": [
      "DATE_TIME_WINDOW_CONFLICT",
      "SHIFT_END_CONFLICT"
    ]
  }
}

Common Unassigned Reasons

Reason	Description
`DATE_TIME_WINDOW_CONFLICT`	Job’s time window doesn’t overlap with any available resource shift
`SHIFT_END_CONFLICT`	Resource shift cannot accommodate the job duration
`WORKING_TIME`	Assignment would violate the resource’s working time constraints
`TRIP_CAPACITY`	Vehicle capacity exceeded
`TAG_HARD`	Resource lacks a required (hard) tag for the job
`TAG_SOFT`	Resource lacks a preferred (soft) tag for the job

Use Cases

Capacity Planning: Identify when you need more resources or extended shifts
Schedule Optimization: Understand which constraints are most restrictive
Customer Communication: Provide clear explanations for service limitations
System Debugging: Quickly identify configuration issues preventing assignments

Incomplete Results

Reasons are derived from the alternative positions computed for each unassigned job, and that analysis is bounded (see Limiting the cost of alternatives). Every unserved job still gets an entry in unservedReasons, but a job that was not analysed gets an empty list - which is indistinguishable from “no hard constraint blocked this job”. The solution carries an explanationTruncation object whenever that can have happened:

{
  "unserved": ["job-1", "job-2", "..."],
  "unservedReasons": { "job-1": ["DATE_TIME_WINDOW_CONFLICT"] },
  "explanationTruncation": {
    "reason": "JOB_LIMIT_EXCEEDED",
    "message": "Explanation limited to 500 of 8186 jobs by maxExplainedJobs.",
    "analysedJobs": 500,
    "totalJobs": 8186
  }
}

An empty reason list only means “no blocking hard constraint” when explanationTruncation is absent. Raise maxExplainedJobs and maxDurationMillis if you need the full picture on a large instance.

Performance Considerations

Setting onlyUnassigned: true improves performance by only analyzing unassigned jobs
For large problems, consider using this feature selectively during debugging
The defaults (maxDurationMillis: 30000, maxExplainedJobs: 500, maxAlternativesPerJob: 25) keep the analysis bounded; without them a heavily unassigned instance can produce gigabytes of alternatives
The explanation process runs after the main optimization, so it doesn’t impact solution quality. It impacts latency however.

Platform

VRP API

Fill API

Overview

Enabling Unassigned Reasons

Example Request

Example Response

Common Unassigned Reasons

Use Cases

Incomplete Results

Performance Considerations

​Overview

​Enabling Unassigned Reasons

​Example Request

​Example Response

​Common Unassigned Reasons

​Use Cases

​Incomplete Results

​Performance Considerations

Overview

Enabling Unassigned Reasons

Example Request

Example Response

Common Unassigned Reasons

Use Cases

Incomplete Results

Performance Considerations