Error "invalid run parameters with API-Driven Runs Workflow

Problem

Introduction

When using the HCP Terraform or Terraform Enterprise API to create a new run, you may encounter a 422 Unprocessable Entity error with the message invalid run parameters. This article explains the cause of this error and how to resolve it by verifying the status of the configuration version.

When you send a POST request to the Runs API endpoint, the operation fails with a 422 status code and an error message indicating invalid run parameters.

The following example shows the failing API request and response.

$ curl \
  --request POST \
  --header "Authorization: Bearer $ADMIN_TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --data @payload.json \
  https://alive-anemone.tf-support.hashicorpdemo.com/api/v2/runs

{"errors":[{"status":"422","title":"unprocessable entity","detail":"invalid run parameters"}]}

Cause

This error occurs if the configuration version specified in the run payload has not finished uploading. The API returns an invalid run parameters error because the referenced configuration version is not yet in a valid state (i.e., uploaded) to start a new run.

Solution

To resolve this issue, you must confirm that the configuration version's status is uploaded before you create the run. You can check the status by sending a GET request to the configuration-versions API endpoint for the workspace.

1. After creating a new configuration version, note its id from the response. The initial status will be pending.

   $ curl \
     --request POST \
     --header "Authorization: Bearer $ADMIN_TOKEN" \
     --header "Content-Type: application/vnd.api+json" \
     --data @payload.json \
     https://alive-anemone.tf-support.hashicorpdemo.com/api/v2/workspaces/ws-hsaGbUNEhhxstjmt/configuration-versions

   The response includes an upload-url and shows the status as pending.

   {
     "data": {
       "id": "cv-ntv3HbhJqvFzamy7",
       "type": "configuration-versions",
       "attributes": {
         "auto-queue-runs": true,
         "error": null,
         "error-message": null,
         "source": "tfe-api",
         "status": "pending",
         "status-timestamps": {},
         "changed-files": [],
         "upload-url": "https://alive-anemone.tf-support.hashicorpdemo.com/_archivist/v1/object/dmF1bHQ6djE6aksvUGhmbVZUQ3BDMWJxeTA5YTNWU2lsU0ppTTZUd0xMMStjdEorSVNpQVRQbGJ6c3JzUVJ6ZHJ5VFVoQytNVUM4K2dZcnY2ZUk0eU5mQmVoclNjQzZOUFRDaU9Fb3JUVUlvYVlCVUZlVHZ0NGcwcXh2Mm1sL2dvcmpvYmRXbjExYjdJOFpiMEF2cWZPZ0RXakp2ZzhadUExcVk1QUs0RThTVXJzUyt4SVcrZ1E0cFlLUUwzcnQ0L3JSWlozN2d2c2pjV0syVjlTaHl5akhBeC9TeTNnbDRLU28zTG1tbVQ3WjFOa1VWTmdoVjNLVGNhMVBjaGxVTStJRTBhT05sSzU1YVM5b2JNNTNQZHFhYjJlOW9Hb3lLNFNlZkd5dzA9"
       },
       "relationships": {
         "ingress-attributes": {
           "data": null,
           "links": {
             "related": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/ingress-attributes"
           }
         }
       },
       "links": {
         "self": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7"
       }
     }
   }

2. After uploading the configuration content, poll the configuration-versions endpoint until the status changes to uploaded.

   $ curl \
     --header "Authorization: Bearer $TOKEN" \
     --header "Content-Type: application/vnd.api+json" \
     --request GET \
     https://alive-anemone.tf-support.hashicorpdemo.com/api/v2/workspaces/ws-hsaGbUNEhhxstjmt/configuration-versions

   The response will show the status as uploaded.

   {
     "data": [
       {
         "id": "cv-ntv3HbhJqvFzamy7",
         "type": "configuration-versions",
         "attributes": {
           "error": null,
           "error-message": null,
           "source": "gitlab",
           "speculative": false,
           "status": "uploaded",
           "status-timestamps": {}
         },
         "relationships": {
           "ingress-attributes": {
             "data": {
               "id": "ia-i4MrTxmQXYxH2nYD",
               "type": "ingress-attributes"
             },
             "links": {
               "related": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/ingress-attributes"
             }
           }
         },
         "links": {
           "self": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7"
         }
       }
     ]
   }

Outcome

Once the configuration version status is uploaded, you can successfully create a new run using its ID in the POST request to the Runs API endpoint. The request will no longer return a 422 error.

Additional Information

• For additional information, see the official documentation on the API-driven workflow.