---

name: graphql-and-webserver description: "Use when a coding agent needs to start or debug dagster-webserver, query Dagster GraphQL through the CLI or Python client, handle path prefixes, headers, auth, remote URLs, read-only webserver mode, or diagnose webserver/API failures." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

GraphQL And Webserver

Use this sub-skill for Dagster OSS webserver and GraphQL API workflows in an installed Dagster Python environment. It covers dagster-webserver, dagster-graphql, the DagsterGraphQLClient, remote GraphQL URLs, path prefixes, headers/auth, read-only serving, and API troubleshooting.

Route Here

• Starting dagster-webserver directly, especially with --host, --port, --path-prefix, --read-only, or logging/database timeout flags.
• Running one-off GraphQL queries with dagster-graphql --text, --file, --predefined, --variables, --remote, or --output.
• Using DagsterGraphQLClient for run status, job submission, repository-location reload/shutdown, run termination, custom headers, custom auth, HTTPS, timeouts, or path prefixes.
• Debugging /graphql, /server_info, workspace target selection, invalid variables JSON, remote URL validation, connection errors, read-only mutation failures, or API response __typename errors.

Route Elsewhere

• Core Dagster asset/job/Definitions modeling: use ../asset-definitions/SKILL.md if that sub-skill exists.
• Local dagster CLI project validation, asset materialization, schedule/sensor commands, or dagster dev: use ../cli-local-development/SKILL.md if that sub-skill exists.
• Production deployment topology, daemon, instance storage, run launchers, Kubernetes, or service operations: use ../deployment-operations/SKILL.md if that sub-skill exists.
• Dagster Plus authorization and cloud deployment administration: treat this sub-skill only as a client/API caution and route cloud operations elsewhere if available.

Start Here

1. Decide whether the task is server-side (dagster-webserver), CLI query (dagster-graphql), or Python client (DagsterGraphQLClient).
2. For server startup, choose a workspace target deliberately: -w/--workspace, -f/--python-file, -m/--module-name, package target flags, -a/--attribute, and -d/--working-directory as appropriate.
3. For GraphQL CLI queries, provide exactly one query source: --text, --file, or --predefined; add --variables as a JSON string only when the query declares variables.
4. For remote webservers, verify the public base URL and path prefix before querying; the GraphQL endpoint is the base URL plus /graphql after any prefix.
5. Use python scripts/graphql_health_check.py --help from this sub-skill directory to inspect safe helper options before any network call.

References

• Workflows and API Reference for concrete webserver, GraphQL CLI, Python client, path-prefix, header/auth, and read-only examples.
• Troubleshooting for install/import failures, optional dependency gaps, CLI/API misuse, connection errors, path-prefix problems, read-only failures, and GraphQL response errors.
• GraphQL health-check script for a safe --dry-run command printer or optional read-only GraphQL health query against a webserver URL.

Safety Notes

• dagster-webserver starts a long-running service; do not launch it as a smoke test unless the user asked to start a server.
• dagster-graphql mutations and DagsterGraphQLClient methods such as submit_job_execution, terminate_run, reload_repository_location, and shutdown_repository_location can mutate deployment state.
• Prefer read-only queries such as version, repositoriesOrError, or run-status lookups when diagnosing connectivity.
• Never print secrets from auth headers or tokens; pass them via environment variables or secret managers and redact them in logs.