dgraph-io/dgraph · error

POST method cannot have query parameters in url: %s

Error message

POST method cannot have query parameters in url: %s

What it means

Dgraph's remote schema introspection is performed with a POST request, so validateUrl rejects any URL containing a query string. If the rawURL supplied in the @custom directive (or remote schema config) has ?... parameters, validation fails before any network call. This keeps introspection requests canonical and cacheable.

Source

Thrown at graphql/schema/remote.go:30

	"io"
	"net/http"
	"net/url"
	"time"

	"github.com/golang/glog"
	"github.com/pkg/errors"

	"github.com/dgraph-io/gqlparser/v2/ast"
)

func validateUrl(rawURL string) error {
	u, err := url.ParseRequestURI(rawURL)
	if err != nil {
		return err
	}

	if u.RawQuery != "" {
		return fmt.Errorf("POST method cannot have query parameters in url: %s", rawURL)
	}
	return nil
}

type IntrospectionRequest struct {
	Query string `json:"query"`
}

// introspectRemoteSchema introspectes remote schema
func introspectRemoteSchema(url string, headers http.Header) (*introspectedSchema, error) {
	if err := validateUrl(url); err != nil {
		return nil, err
	}
	param := &IntrospectionRequest{
		Query: introspectionQuery,
	}

	body, err := json.Marshal(param)

View on GitHub (pinned to 759e242be6)

Solutions

1. Remove the query string from the remote URL and keep only the bare endpoint path
2. Move any parameters into HTTP headers via the forward/custom header configuration instead
3. If auth via query param is unavoidable, configure a proxy endpoint without query params

Example fix

// before
url: "https://api.example.com/graphql?env=prod"
// after
url: "https://api.example.com/graphql"

function assertCleanUrl(u) {
  const parsed = new URL(u)
  if (parsed.search) throw new Error(`POST remote url must not have query params: ${u}`)
}

func hasNoRawQuery(rawURL string) bool {
  u, err := url.ParseRequestURI(rawURL)
  return err == nil && u.RawQuery == ""
}

err := schema.ValidateCustom(dgSchema, gqlSchema)
if err != nil && strings.Contains(err.Error(), "cannot have query parameters") {
  log.Printf("strip query params from remote url: %v", err)
}

When it happens

Trigger: Configuring a @custom directive with a remote GraphQL URL like https://api.example.com/graphql?env=prod and running schema validation (validateUrl called via introspectRemoteSchema).

Common situations: Copying URLs from browsers that appended tracking/query params; putting API keys in the URL query string; environment selectors in URLs.

Related errors

• remote schema doesn't have any queries.
• given GraphQL operation is not a subscription
• while json unmarshaling result from remote introspection que
• NQuad failed sanity check. Subject: %q, Predicate: %q, Objec
• empty variable name in function call

AI-assisted analysis of dgraph-io/dgraph@759e242be6 (2026-09-01). Data as JSON: /api/errors/66260b942b4872dd. Report an issue: GitHub.