Troubleshoot common issues

  • Fleet Engine implementations should be designed to handle failures and potential data loss by recreating vehicles and tasks when necessary.

  • In case of Fleet Engine failures, use a backoff strategy to manage the recreation rate and avoid quota issues.

  • Implement retries for Fleet Engine requests to address occasional failures, leveraging client library defaults or custom mechanisms.

  • Driver apps should autonomously restore state after crashes by recreating tasks and stops within the Driver SDK, relying on error handling for existing entities.

Check the following sections for help if you experience any issues.

Lost state in Fleet Engine

When working with Fleet Engine, design your implementation to anticipate failures. For example, if you issue a request to Fleet Engine to update a vehicle, it might respond with an error indicating that the vehicle does not exist. Your implementation should then recreate the vehicle in the new state.

In the extremely unlikely scenario of a catastrophic failure of Fleet Engine, you may need to recreate most or all vehicles and tasks. If the creation rate becomes too high, some requests may fail again due to quota issues since quota checks are in place to avoid denial of service (DOS) attacks. In this case, slow down the recreation rate using a backoff strategy for reattempts.

Retries

Be sure your system implements retries for requests to Fleet Engine since they might fail occasionally. Fleet Engine client libraries issue retries by default.

Lost state in the driver app

If the driver app crashes, the app must recreate the current state within the Driver SDK. The app should attempt to recreate tasks to ensure that they exist and to restore their current states. The app should also recreate and explicitly set the list of stops for the Driver SDK.

Note: These restorations must be done autonomously without relying on information from Fleet Engine, other than errors indicating if and when an entity already exists in the database. If an entity does already exist, then that error can be absorbed and the entity can be updated using its ID.

Deadline exceeded errors

If you get a DEADLINE_EXCEEDED error when calling Fleet Engine, the request took longer than the configured timeout. Fleet Engine client libraries have default timeouts, but you might need to adjust them.

For general information on gRPC deadlines, see gRPC and Deadlines.

To configure the deadline when using the Fleet Engine Java client library, you can adjust the RPC retry settings. The following example shows how to configure a custom timeout when setting up the VehicleService:

VehicleServiceSettings.Builder settingsBuilder = VehicleServiceSettings.newBuilder();

// Set the timeout to 10 seconds.
settingsBuilder
    .getVehicleSettings()
    .setRetrySettings(
        settingsBuilder.getVehicleSettings().getRetrySettings().toBuilder()
            .setTotalTimeout(java.time.Duration.ofSeconds(10))
            .build());

VehicleServiceClient client = VehicleServiceClient.create(settingsBuilder.build());

Common API errors

This section lists common API errors you might encounter, their causes, and how to resolve them.

NOT_FOUND (HTTP 404)

The requested entity (like a vehicle, trip, or task) couldn't be found.

  • Cause: Usually caused by attempting to get, update, or delete an entity using an ID that doesn't exist in the database.
  • Remediation: Verify that the entity ID is correct and that the entity was successfully created before you attempt to access it.

ALREADY_EXISTS (HTTP 409)

The entity you are trying to create already exists.

  • Cause: Caused by calling a create method (like CreateVehicle or CreateTrip) with an ID that is already in use.
  • Remediation: Either update the existing entity instead, or use a new unique ID for the creation request.

PERMISSION_DENIED (HTTP 403)

You don't have the required permissions to complete the request.

  • Cause: This typically occurs if your JSON Web Token (JWT) is missing the correct claims, or if the service account signing the JWT is missing the required IAM roles. For example, "JWT does not contain a matching scope for requested trip."
  • Remediation: Check your Service Account permissions and ensure your JWT claims include the correct scopes for the entity you are trying to access.

INVALID_ARGUMENT (HTTP 400)

One or more of the arguments passed in the request are invalid.

  • Cause: This can happen for various reasons, such as providing an out-of-range value (e.g., maximum capacity), missing a required field (e.g., a VehicleType), or providing invalid coordinates for a pickup point.
  • Remediation: Review the error message for the specific field that is invalid and ensure your request conforms to the API specification.

FAILED_PRECONDITION (HTTP 400)

The operation was rejected because the system is not in a state required for the operation's execution.

  • Cause: Common causes include attempting to change a COMPLETE or CANCELED trip to a different state, or trying to assign a CLOSED task to a vehicle.
  • Remediation: Ensure the entity's current state allows the operation you are attempting. Check the error message for specific state violations.

UNAVAILABLE (HTTP 503)

The service is unavailable.

  • Cause: This indicates a transient issue with the Fleet Engine service.
  • Remediation: The request can safely be retried with exponential backoff.