Skip to main content

Error Handling

This page discusses common error scenarios, HTTP status codes, and troubleshooting tips you may encounter when using the Terraform Editor API. Understanding how errors are reported will help you debug issues quickly and keep your workflow running smoothly.

Error Response Structure​

When something goes wrong, the API returns a JSON body with:

{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "location": "terraform-edit"
  },
  "message": "string"
}
  • success: Always false for error responses.
  • error.code: Short code describing the issue (e.g., "INVALID_REQUEST", "AMBIGUOUS_MATCH", etc.).
  • error.message: More human-readable description of the problem.
  • error.location: Typically "terraform-edit", indicating which part of the system generated the error.
  • message: Mirrors the error.message or provides additional context.

Common Error Codes​

Below are some frequent error codes you might see, along with suggestions on how to resolve them.

1. MISSING_CODE​

  • When It Happens: The request body doesn't include the required code field.
  • Fix: Provide "code" with your Terraform configuration string.

2. INVALID_REQUEST​

  • When It Happens:
    • The JSON request is malformed or missing required fields.
    • The edits field doesn't contain at least one operation key (add, update, set, or delete).
    • An internal parsing issue occurred due to incorrect JSON structure.
  • Fix: Verify you have a valid JSON structure and that code and edits are present.

3. AMBIGUOUS_MATCH​

  • When It Happens: An update, delete, or set operation matches more than one block without selectors.
  • Fix: Use index, where, or labels to narrow down the target block. If you need to modify multiple blocks, include multiple array items or use separate operations.

4. BLOCK_NOT_FOUND or NO_MATCH​

  • When It Happens: An update, delete, or set operation can't find any block matching the provided type/name/selector.
  • Fix: Confirm the block actually exists in your code. If you're trying to create it, use add or set. If you're sure it should exist, double-check your labels, where attributes, or names.

5. DUPLICATE_BLOCK​

  • When It Happens: An add operation tries to create a block that already exists (same type/name).
  • Fix: If you intend to update the existing block, use update or set. If you truly want a second block, adjust the label or name.

6. METHOD_NOT_ALLOWED​

  • When It Happens: You used an HTTP method other than POST.
  • Fix: Send your request with POST.

7. JSON_PARSE_ERROR​

  • When It Happens: The server can't parse your request body due to malformed JSON.
  • Fix: Validate your JSON, remove trailing commas or extra quotes, ensure it's syntactically correct.

HTTP Status Codes Recap​

  • 200 OK: The request was successful; success: true.
  • 400 Bad Request: Client-side error—check your JSON structure, required fields, or ambiguous operations.
  • 405 Method Not Allowed: You used a non-POST request method.
  • 500 Internal Server Error: Unexpected server error—check logs or contact support if it persists.

Troubleshooting Checklist​

  1. Validate Your JSON
    • Make sure code is a string.
    • Confirm edits is either a well-formed object or a valid JSON string.
  2. Include at Least One Operation
    • At least one of add, update, set, or delete must be present.
  3. Avoid Ambiguity
    • If multiple blocks share the same type/name, use selectors (where, index, labels) to target the correct block.
  4. Check for Typos
    • A single spelling mistake (like "aws_intance" instead of "aws_instance") can prevent the API from finding your block.
  5. Verify Terraform Compatibility
    • After you get edited_code, run terraform validate to ensure it's valid Terraform syntax.

Example Error Response​

Below is an example of an ambiguous match error. Suppose you have two aws_instance blocks named "main" and run an update operation without selectors:

{
  "success": false,
  "error": {
    "code": "AMBIGUOUS_MATCH",
    "message": "Multiple blocks match aws_instance.main; use selectors to disambiguate",
    "location": "terraform-edit"
  },
  "message": "Multiple blocks match aws_instance.main; use selectors to disambiguate"
}

Resolution: Add a where, index, or labels field to specify which instance you want to update.

When to Contact Support​

If you've gone through the checklist and still encounter unexplained errors:

  • Check our FAQ for additional tips on common edge cases.
  • Reach out to our support team via email or community forums, providing:
    • The request JSON you're sending (minus any sensitive info).
    • The full error response from the API.
    • Any logs or Terraform output that could help diagnose the problem.

Next Steps

  • Review the API Reference for request/response structures.
  • Explore FAQ if you still have unanswered questions.
  • For deeper dives into usage patterns, check out our Guides and the Examples.