GraphQL Query Repair Prompt

This prompt is for production engineers and API developers who generate GraphQL queries through LLMs and need a reliable repair step when queries fail validation. Use it when a generated query references fields that do not exist in the target schema, omits required arguments, passes arguments of the wrong type, or nests selections incorrectly. The prompt works by providing the model with schema introspection results and few-shot examples of broken-to-fixed query pairs. It is designed to be called after a query fails client-side or server-side validation, not as a first-pass query generator.

The ideal user has access to the target GraphQL schema's introspection output—typically the result of a standard introspection query—and a record of the exact validation error returned by the server. The prompt requires three concrete inputs: the invalid query string, the schema introspection JSON, and the validation error message. Without all three, the model lacks the grounding necessary to produce a correct repair. The repair itself is a structural operation: renaming fields to match the schema, adding missing required arguments, coercing argument types, and fixing nested selection sets. It is not a semantic rewrite or query optimization step.

You should not use this prompt when the schema is unavailable, when the query is intentionally exploratory, or when the failure is due to authentication, rate limiting, or network errors rather than structural query problems. This prompt is also inappropriate for queries that are syntactically valid but semantically wrong—for example, a query that returns an empty result because it filters on a non-existent value. In those cases, the problem is in the application logic, not the query structure. For high-risk production environments, always validate the repaired query against the schema before execution and log both the original error and the repair diff for auditability.

This prompt template is designed to repair a generated GraphQL query that has failed validation against a target schema. It expects the invalid query, the schema introspection results (types, fields, arguments, enums), and the specific validation error message. The model is instructed to produce a corrected, valid query and explain each change it made. The template uses few-shot examples to teach the model common repair patterns: fixing misspelled field names, adding missing required arguments, correcting type mismatches, and removing nonexistent fields.

textCopy
You are a GraphQL query repair assistant. Your task is to fix an invalid GraphQL query so that it passes validation against the provided schema.

## INPUT
- Invalid Query:
```graphql
[INVALID_QUERY]

• Schema Introspection Result (JSON):

jsonCopy
[SCHEMA_INTROSPECTION_JSON]

• Validation Error:

codeCopy
[VALIDATION_ERROR_MESSAGE]

REPAIR RULES

1. Only use field names, argument names, and types that exist in the provided schema introspection.
2. If a required argument is missing, add it with a sensible placeholder value (e.g., "PLACEHOLDER" for strings, 0 for Ints, true/false for Booleans).
3. If a field name is misspelled, correct it to the closest matching field in the schema.
4. If a field does not exist and no close match is found, remove that field and its sub-selection entirely.
5. If an argument value has the wrong type, coerce it to the correct type if possible; otherwise, replace it with a placeholder.
6. Preserve the original query structure, aliases, and fragments as much as possible.
7. Do not add new fields or functionality beyond what is necessary to fix the error.

EXAMPLES

Example 1: Misspelled Field Name

Invalid Query:

graphqlCopy
query {
  user(id: "1") {
    fullname
    email
  }
}

Schema (relevant): User type has fields: id, fullName, email Error: Cannot query field "fullname" on type "User". Did you mean "fullName"? Fixed Query:

graphqlCopy
query {
  user(id: "1") {
    fullName
    email
  }
}

Explanation: Corrected fullname to fullName based on schema suggestion.

Example 2: Missing Required Argument

Invalid Query:

graphqlCopy
query {
  search {
    results {
      title
    }
  }
}

Schema (relevant): search(term: String!) returns SearchResult Error: Field "search" argument "term" of type "String!" is required, but it was not provided. Fixed Query:

graphqlCopy
query {
  search(term: "PLACEHOLDER") {
    results {
      title
    }
  }
}

Explanation: Added missing required argument term with a placeholder value.

Example 3: Nonexistent Field

Invalid Query:

graphqlCopy
query {
  product(sku: "ABC") {
    name
    manufacturer
    weight
  }
}

Schema (relevant): Product type has fields: name, brand, price Error: Cannot query field "manufacturer" on type "Product". and Cannot query field "weight" on type "Product". Fixed Query:

graphqlCopy
query {
  product(sku: "ABC") {
    name
    brand
    price
  }
}

Explanation: Removed nonexistent fields manufacturer and weight. No close match found in schema.

OUTPUT FORMAT

Return a JSON object with the following structure:

jsonCopy
{
  "fixed_query": "<the complete corrected GraphQL query as a string>",
  "changes": [
    {
      "type": "field_rename | field_removal | argument_added | argument_type_coerced | type_coercion",
      "location": "<path to the changed element, e.g., query.user.fullName>",
      "original": "<original value or description>",
      "replaced_with": "<new value or description>",
      "reason": "<brief explanation referencing the schema or error>"
    }
  ],
  "still_has_placeholders": true_or_false
}

CONSTRAINTS

• Do not modify the query if it is already valid.
• If the error cannot be resolved with the provided schema, set fixed_query to an empty string and explain why in the first change entry.
• Always validate that the fixed query uses only types and fields present in the introspection result.
• If you must use a placeholder value, set still_has_placeholders to true.

CURRENT TASK

Repair the invalid query above using the provided schema introspection and error message.

To adapt this template for your own system, replace the four bracketed placeholders before sending it to the model. [INVALID_QUERY] should contain the full GraphQL query string that failed validation. [SCHEMA_INTROSPECTION_JSON] must be the JSON output of a standard GraphQL introspection query against the target endpoint—include at minimum the types array with name, fields, and inputFields for relevant types. [VALIDATION_ERROR_MESSAGE] should be the exact error string returned by your GraphQL validator. If your validator returns multiple errors, concatenate them with newlines. The examples inside the prompt are fixed and should not be replaced; they teach the model the repair patterns. If your domain has different common failure modes (e.g., fragment spread errors, directive misuse), add one or two domain-specific examples following the same format. Keep the total prompt under 3000 tokens to leave room for the introspection JSON, which can be large. For high-risk production use where a bad repair could corrupt data, always run the fixed_query through your GraphQL validator before execution and flag any output where still_has_placeholders is true for human review.

After copying this template, wire it into a repair harness that validates the returned fixed_query against your schema before accepting it. If validation fails again, you can feed the new error back into the prompt for a second repair attempt, but limit retries to a maximum of two to avoid infinite loops. Log every repair attempt with the original query, the error, the fixed query, and the list of changes for auditability. For queries that touch write operations (mutations), require explicit human approval before execution regardless of validation success.

The GraphQL Query Repair Prompt is designed to sit inside a repair loop that activates after a generated or user-submitted query fails initial validation against the target GraphQL schema. The harness should catch the validation error, extract the error details (invalid field names, missing required arguments, type mismatches), and pass them alongside the original query and the relevant schema introspection results into the prompt. This is not a prompt you fire once and forget—it is a corrective step in a multi-stage pipeline where the primary goal is to reduce manual intervention and retry overhead while never silently accepting a query that still fails schema validation.

Integration flow: (1) The application receives a GraphQL query string. (2) Validate it against the live schema using a server-side validator like graphql-js's validate function or your API gateway's schema enforcement. (3) If validation passes, execute the query. (4) If validation fails, collect the error messages, the offending query, and a compact schema representation (types, fields, required arguments, enums) from introspection. (5) Populate the prompt template's [INVALID_QUERY], [VALIDATION_ERRORS], and [SCHEMA_CONTEXT] placeholders. (6) Call the model with the repair prompt. (7) Extract the repaired query from the model's structured output. (8) Re-validate the repaired query against the schema. (9) If it passes, execute it. If it fails again, either retry with enriched error context or escalate to a human review queue with the full failure history. Never execute a query that hasn't passed schema validation.

Model choice and configuration: Use a model with strong code and structured output capabilities. Set temperature low (0.0–0.2) to minimize creative drift in query structure. Require structured output matching a schema like { repaired_query: string, changes: [{ field: string, original: string, repaired: string, reason: string }] } so you can log exactly what was changed and why. Retry budget: Cap repair attempts at 2–3 before escalating. Each retry should include the new validation errors, not just the original ones. Logging: Log the original query, validation errors, schema snapshot hash, repaired query, changes array, and final validation result. This audit trail is essential for debugging repair failures and detecting schema drift where the introspection data no longer matches the live schema.

Failure modes to instrument: Watch for (a) the model hallucinating field names that don't exist in the schema, (b) removing required arguments instead of providing valid values, (c) changing query semantics while making it syntactically valid, and (d) producing a repaired query that passes validation but returns empty or wrong data. Instrument an eval step that compares the repaired query's field selection against the original intent where possible. Human review trigger: If the repair loop exhausts its retry budget, surface the full repair attempt history to a developer queue. Include the original query, each repair attempt, the validation errors at each step, and the schema context used. This gives the human reviewer enough context to either manually fix the query or identify a schema documentation gap that confused the model.

Schema context sizing: GraphQL schemas can be large. Don't dump the entire introspection result into [SCHEMA_CONTEXT]. Extract only the types, fields, arguments, and enums relevant to the query's root types and the fields referenced in the error messages. A good heuristic: include the full type definitions for any type mentioned in a validation error, plus the query, mutation, or subscription root types. This keeps token usage manageable and focuses the model on the parts of the schema that matter for the repair. If the schema is small enough to fit entirely within the context window, include it all to avoid missing indirect type dependencies.