Troubleshoot Common Errors

Common Errors and How to Solve Them

This topic covers solutions to common errors you might encounter with using StepZen.

Connection Errors


{"errors":[{"message":"401 Unauthorized: missing or not allowed","code":401}]}

The StepZen production endpoint can only be called together with your StepZen API key. You need to set the API Key in the header, when you send a request to this endpoint:

Authorization: apikey {APIKEY}

See Connecting to StepZen for more information.

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 this: It also creates a local proxy for your endpoint that you can use to explore the API with GraphiQL.

The endpoint you should use in your application is the production endpoint (in example This endpoint can only be called when you pass your StepZen API key to it, see Connecting to StepZen for more information.

You can only use the localhost endpoint for GraphiQL in the browser. For network requests, you must use the actual GraphQL endpoint that was created. Since the local proxy is only used for development of your endpoint, it makes requests using the Admin key by default. If it were a true proxy, it could create a security vulnerability. To prevent that, the proxy only accepts requests coming from the stepzen start web app running in your browser.

StepZen CLI Errors

EACCES Errors with node Global Install

If you're running into EACCES errors with installing StepZen's cli globally, we recommend consulting npm's official documentation.

GraphQL Errors

If StepZen's CLI displays GraphQL errors, it is helpful to check for a typo 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, and here you can see that the error indicates a type should be spelled with a capital 'C' to be referenced properly.

Another GraphQL error you might run into looks like:

Your local schema has the following GraphQL errors:

Error: Cannot find file graphql/ap_spacex_land.graphql

This means StepZen cannot find the file in the path specified in index.graphql. Correcting the typo (a missing i in graphql/ap_spacex_land.graphql) in the file resolves the problem:

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

GraphiQL Errors

HTTP Error

If you see the error below, this usually means there's an issue with your URL when you make the request:

  "errors": [
      "message": "Connector: HTTP Error: Bad Request",
      "locations": [
          "line": 2,
          "column": 3

Check if the URL is formatted correctly.

Failed to Fetch

If you press play and receive the response below, this often means that your endpoint is not currently working:

  "message": "Failed to fetch",
  "stack": "TypeError: Failed to fetch"

Double check 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 get the error when using the following query on the SpaceX API:

query MyQuery {
  capsules {


  "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:

    find: CapsulesFind
<!--     limit should be here -->
    offset: Int
    order: String
    sort: String
  ): [Capsule]
      endpoint: ""

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 you're referring to a field that's unavailable for one reason or another. For example, a typo, or perhaps an unrefreshed page.

Schema Errors

Errors with Duplicate Types and Fields Caused by File Folder Choices

When creating StepZen projects in your local directory structure, it's best practice to make each project (that connects to a StepZen-hosted endpoint) exist in its own subdirectory.

StepZen 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 StepZen CLI. stepzen.config.json is one example of a StepZen-created file that must not be in your root directory. Placing it there can result in errors similar to the following:

"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're connecting to a PostgreSQL database and get a database error when querying your StepZen 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 How to connect to a PostgreSQL database for more information.


A Helpful Query to Add to your Schema When Things Go Wrong

This schema uses 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: "$id")

The endpoint$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.

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 backend from StepZen.

Debugging Header

To see helpful debugging information from StepZen, add these headers to your request:

{"Stepzen-Debug-Level": 1, "Authorization" :"apikey PLACE_YOUR_ADMIN_KEY_HERE

You'll see the response that StepZen 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.

Queries Work in localhost But Not Against the Other Endpoint

If you're getting responses in your localhost proxy with GraphiQL, but not when you make a direct query against the endpoint from your frontend, and you're not sending headers in your request, rest assured that this is exactly how the development process is supposed to work. There's a difference between a localhost endpoint and a deployed endpoint.


'localhost' means the current machine you're logged into and working on. In many cases, this is your desktop or laptop computer. When you're using the GraphiQL web page with a 'localhost' address, opened from a URL provided by the StepZen CLI (Command Line Interface), that means that the requests you're sending and the data you're seeing are passed to and from our StepZen server through a proxy that runs on your machine. That proxy automatically adds authorization keys. This is why you don't need to send keys when accessing your StepZen API through a 'localhost' URL (which is accessible only to you), but you do need to add an Authorization HTTP header when accessing you StepZen API through its public URL.

Try it out. Navigate to your StepZen folder, and run stepzen start. You'll see a url in the output that starts with localhost:5001. When you visit the GraphiQL interface it sends you towards, you can make queries without sending any authorization headers because it's hosted directly on your machine.

Deployed Endpoint

When you run stepzen start, it uploads and deploys the schema in the current directory to the StepZen server. So, when you visit the endpoint url that looks like, you should expect to see an error like this in the browser:

{"errors":[{"message":"403 Forbidden","code":403}]}

This means your API is working the way it should! It is protecting your endpoint from being accessed by anyone on the internet. It could also be a '401 not authorized error'. To access the response, you need to send an authorization header with the request. You can see how to send these headers in our section of the docs that explains how to consume GraphQL.

This site uses cookies: By using this website, you consent to our use of cookies in accordance with our Website Terms of Use and Cookie Policy.