facebook/relay · error

BabelPluginRelay: Unexpected empty graphql tag.

Error message

BabelPluginRelay: Unexpected empty graphql tag.

What it means

getValidGraphQLTag parses the tag's raw text and throws if the resulting document has zero definitions — i.e. the graphql`` tag is empty or contains only whitespace/comments. Relay cannot compile an empty document, and an empty tag is almost certainly a coding mistake.

Source

Thrown at packages/babel-plugin-relay/getValidGraphQLTag.js:44

  if (!tag.isIdentifier({name: 'graphql'})) {
    return null;
  }

  const quasis = path.node.quasi.quasis;

  if (quasis.length !== 1) {
    throw new Error(
      'BabelPluginRelay: Substitutions are not allowed in graphql fragments. ' +
        'Included fragments should be referenced as `...MyModule_propName`.',
    );
  }

  const text = quasis[0].value.raw;

  const ast = GraphQL.parse(text, {experimentalFragmentVariables: true});

  if (ast.definitions.length === 0) {
    throw new Error('BabelPluginRelay: Unexpected empty graphql tag.');
  }

  return ast;
}

module.exports = getValidGraphQLTag;

View on GitHub (pinned to 668b1b85e0)

Solutions

1. Add a valid fragment or operation to the graphql tag
2. Remove the unused empty graphql tag and its variable if it is dead code
3. Restore the deleted document if it was removed accidentally (check version control)

Example fix

// before
const frag = graphql``;

// after
const frag = graphql`fragment F on User { id }`;

function assertNonEmptyTag(text) {
  const trimmed = text.trim();
  if (!trimmed) throw new Error('graphql tag must not be empty');
  const { parse } = require('graphql');
  if (parse(trimmed).definitions.length === 0) {
    throw new Error('graphql tag parsed to zero definitions');
  }
}

const isNonEmptyGraphQL = (text) =>
  typeof text === 'string' && text.trim().length > 0;

When it happens

Trigger: graphql`` or graphql` ` with no GraphQL text; a tag whose contents were deleted/commented out leaving nothing parseable; conditional string building that ended up empty (before the interpolation check).

Common situations: Refactoring that emptied a tag temporarily; git merge conflicts resolved leaving a blank tag; auto-generated code where the template string source is empty.

Related errors

• BabelPluginRelay: Expected exactly one definition per graphq
• BabelPluginRelay: Expected a fragment, mutation, query, or s
• GraphQL operations and fragments must contain names
• BabelPluginRelay: Substitutions are not allowed in graphql f
• BabelPluginRelay: Expected plugin context to include "types"

AI-assisted analysis of facebook/relay@668b1b85e0 (2026-09-02). Data as JSON: /api/errors/3715c634af38b8f8. Report an issue: GitHub.