Resolving common errors

Take a look at common errors raised in the GraphiQL browser and the CLI, and learn how to resolve them.

Connection errors

Unauthorized
The following error indicates that you called an API but failed to provide your API key:
{"errors":[{"message":"401 Unauthorized: missing or not allowed","code":401}]}

The production endpoint can only be called with your API key. Set the API key in the header when you send a request to this endpoint:

Authorization: apikey {APIKEY}

Contact your API Connect for GraphQL administrator to obtain your API key.

Cannot POST to GraphQL endpoint
When you create a development environment on your local machine using stepzen start, it returns an endpoint for your GraphQL API that looks like the following example: https://<domain>/api/financials/__graphql

The endpoint can only be called when you pass your API key to it.

CLI errors

EACCES errors with node Global Install
If you receive EACCES errors with installing globally, see the Resolving EACCES permissions errors when installing packages globally in the npm documentation.
GraphQL errors in the CLI
If the CLI displays GraphQL errors, it is helpful to check for a typing mistake in your GraphQL schema. For example:
Starting...... !

Your local schema has the following GraphQL errors:

Error: Unknown type "continentFilterInput".
Did you mean "ContinentFilterInput" or "LanguageFilterInput"?

GraphQL is case-sensitive; the error indicates that the type should be spelled with an uppercase "C" to be referenced correctly.

Another GraphQL error you see looks like:

Your local schema has the following GraphQL errors:

Error: Cannot find file graphql/ap_spacex_land.graphql

This means that API Connect for GraphQL cannot find the file in the path specified in index.graphql. Correcting the filename and path (in this example, adding the missing i in ap_spacex_land) in the filename resolves the problem:

schema @sdl(files: ["graphql/api_spacex_land.graphql"]) {
  query: Query
}

GraphiQL errors

HTTP error
If you see the following error, it usually means there's an issue with the URL where you made the request:
  "errors": [
    {
      "message": "Connector: HTTP Error: Bad Request",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],

Make sure the URL is formatted correctly.

Failed to fetch
If you execute an API and receive the following response, it often means that your API Connect for GraphQL endpoint is not available:
{
  "message": "Failed to fetch",
  "stack": "TypeError: Failed to fetch"
}

Verify that stepzen start is running.

Cannot query field on type
Sometimes querying a field can fail, resulting in an error stating Cannot query field ... on type. For example, you might see the error when using the following query on the SpaceX API:
query MyQuery {
  capsules {
    id
    limit
    landings
    original_launch
    reuse_count
  }
}

Response:

{
  "data": null,
  "errors": [
    {
      "message": "Cannot query field \"limit\" on type \"Capsule\".",
      "locations": [
        {
          "line": 4,
          "column": 5
        }
      ]
    }
  ]
}

This error occurs because limit is not defined on the capsules type inside the schema file:

  capsules(
    find: CapsulesFind
<!--     limit should be here -->
    offset: Int
    order: String
    sort: String
  ): [Capsule]
    @graphql(
      endpoint: "https://api.spacex.land/graphql/"
    )

Adding the field to the capsules type resolves the problem.

In general, an error indicating that you can't query a field on a type means that you are referring to a field that's unavailable for some reason (such as a spelling error or an unrefreshed page).

Schema errors

Errors with duplicate types and fields caused by file folder choices
When creating API Connect for GraphQL project workspaces in your local directory structure, it's best practice to make sure that each project resides in its own subdirectory.

API Connect for GraphQL looks for configuration files by traversing the directory hierarchy to the root folder, so files must exist in the directory from where you run the API Connect for GraphQL CLI. The stepzen.config.json file is one example of an API Connect for GraphQL-created file that must not be stored in your root directory. Placing it there can result in errors similar to the following message:

"Error: There can be only one type named "Entities".
"Error: There can be only one type named "Public_metrics".
...

Database errors

Connecting to PostgreSQL
When you connect to a PostgreSQL database and g et a database error while querying your API Connect for GraphQL API, this might be related to your connection string in the config.yaml file in your project. Make sure the value for uri has quotes around it and any special characters (like symbols) are URL encoded. See Connecting a PostgreSQL database for more information.

Debugging

A helpful query to add to your schema when things go wrong
The following schema uses httpbin.org to return information about your request:
type debug {
  args: JSON
  data: JSON
  files: JSON
  form: JSON
  headers: JSON
  json: JSON
  method: String
  url: String
}

type Query {
  debugger(id: String!): debug
    @rest(endpoint: "https://httpbin.org/anything/$id")
}

The endpoint https://httpbin.org/anything/$id returns back what it receives, and the web page shows the results visually. For example, the response could help you verify that the URL is being formatted as expected.

The id is optional. If you've got an ID you want to check on, passing it via id provides a nice way to see what gets sent to the API Connect for GraphQL from API Connect for GraphQL.

Debugging header
To see helpful debugging information from API Connect for GraphQL, add these headers to your request:
{"Stepzen-Debug-Level": 1, "Authorization" :"apikey PLACE_YOUR_ADMIN_KEY_HERE"}

You'll see the response that API Connect for GraphQL is returning, including information like diagnostics, with fields like duration and path, as well as the response, with fields like headers, data, and status code.