Dagster GraphQL

Common errors

• ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))

  cause The `DagsterGraphQLClient` cannot establish or maintain a connection with the Dagster GraphQL server, often due to the server being down, an incorrect hostname or port, or network connectivity issues.
  fix Verify that the Dagster GraphQL server (typically `dagit`) is running and accessible at the specified `hostname` and `port_number`, and check network configurations or firewalls.

• DagsterGraphQLClientError: PipelineNotFoundError

  cause The GraphQL query submitted via the client refers to a pipeline or job name that does not exist in the targeted Dagster repository location.
  fix Ensure that the `job_name`, `repository_location_name`, and `repository_name` provided to methods like `submit_job_execution` or `get_run_status` are correct and match an existing definition in your Dagster deployment.

• DagsterGraphQLClientError: JobConfigValidationInvalid

  cause The `run_config` provided for a job execution does not conform to the expected configuration schema of that particular Dagster job.
  fix Review the job's configuration schema and adjust the `run_config` dictionary to correctly match the required structure and types.

• ModuleNotFoundError: No module named 'CODE_LOCATION_NAME_PLACEHOLDER'

  cause The Python environment where Dagster is attempting to load a code location cannot find the specified module, usually because the project is not correctly installed or its structure is misconfigured.
  fix Ensure your Dagster project is installed in the Python environment, typically by running `pip install -e .` from your project root, and that all necessary dependencies are present. Also verify the `module_name` in your `workspace.yaml` or `dagster.yaml` is correct.

• requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: http://yourorg.dagster.cloud/prod/graphql

  cause The request to the Dagster GraphQL API is missing or contains an invalid authentication token/header, leading to an unauthorized access attempt, especially when connecting to Dagster Cloud or a secure self-hosted instance.
  fix When initializing `DagsterGraphQLClient` for Dagster Cloud, ensure you pass a valid user token in the `headers` parameter as `{'Dagster-Cloud-Api-Token': 'your_token_here'}`. For self-hosted instances with authentication, provide the appropriate headers or authentication mechanism.

Warnings

• breaking Python 3.9 support has been dropped. The minimum supported Python version for `dagster-graphql` (and Dagster core) is now 3.10. Users on Python 3.9 must upgrade their Python environment.
  Fix: Upgrade Python environment to 3.10 or newer (up to 3.14).
• deprecated The `reload_repository_location` API method in `DagsterGraphQLClient` is slated for removal in Dagster version 2.0.
  Fix: Review your code for usage of `client.reload_repository_location` and consult Dagster documentation for alternatives as version 2.0 approaches.
• gotcha The `dagster-graphql` package currently includes the entire `dagster` package and its sub-dependencies, which can lead to a large number of transitive dependencies. This might cause dependency clashes in complex environments or when integrating into lightweight applications.
  Fix: Be mindful of your dependency tree. If clashes occur, consider isolating environments (e.g., using virtual environments) or manually crafting GraphQL requests if the `DagsterGraphQLClient`'s convenience is outweighed by dependency issues. The core GraphQL API can be interacted with directly using any HTTP client.
• gotcha The Dagster GraphQL API is still evolving, and certain parts (especially those primarily for internal use by the Dagster webserver) are subject to breaking changes.
  Fix: Always refer to the official Dagster release notes and GraphQL API documentation before upgrading to anticipate and address potential breaking changes, especially if relying on less commonly used API endpoints.
• gotcha When querying logs for a run or events, the GraphQL API applies a default limit of 1000 items. To retrieve all logs, you must use the `cursor` field in the response to paginate through subsequent results.
  Fix: Implement pagination logic using the `cursor` field when querying `logsForRun` or `eventConnection` resolvers to ensure complete data retrieval.
• gotcha To reliably fetch job configuration schemas, use the `runConfigSchemaOrError` query rather than trying to extract `runConfigYaml` from `runsOrError`. Old runs or pruned data may result in `runConfigYaml` being empty or omitted, making it unreliable for reconstructing job configurations.
  Fix: For fetching a job's default or current configuration schema, query `runConfigSchemaOrError` directly against the job definition. For past run configurations, be aware of data retention policies.

Install

• pip install dagster-graphql Install latest version

Imports

• DagsterGraphQLClient

  from dagster_graphql import DagsterGraphQLClient

  This is the primary client for programmatic interaction with the Dagster GraphQL API.

Quickstart

This quickstart demonstrates how to initialize the `DagsterGraphQLClient` and execute a raw GraphQL query to fetch recent Dagster runs. For Dagster Cloud, you would configure the client with your deployment URL and a user token. Ensure a Dagster instance (e.g., via `dagster dev`) is running and accessible at the specified host and port for the local example.

import os
from dagster_graphql import DagsterGraphQLClient

# Configure client for local Dagster instance or Dagster Cloud
# For local: DagsterGraphQLClient("localhost", port_number=3000)
# For Dagster Cloud:
# url = os.environ.get("DAGSTER_CLOUD_URL", "YOUR_ORG.dagster.cloud/prod")
# token = os.environ.get("DAGSTER_CLOUD_API_TOKEN", "YOUR_TOKEN")

# Example for a local Dagster instance (run 'dagster dev' first)
client = DagsterGraphQLClient("localhost", port_number=3000)

try:
    # Example: Get a list of recent runs
    runs_query = """
    query LatestRuns {
        runsOrError {
            __typename
            ... on Runs {
                results {
                    id
                    status
                    pipelineName
                }
            }
            ... on PythonError {
                message
            }
        }
    }
    """
    result = client._execute(runs_query) # _execute is used for raw GraphQL queries

    if result and result.get("runsOrError", {}).get("__typename") == "Runs":
        print("Recent Dagster Runs:")
        for run in result["runsOrError"]["results"]:
            print(f"  ID: {run['id']}, Status: {run['status']}, Job: {run['pipelineName']}")
    elif result and result.get("runsOrError", {}).get("__typename") == "PythonError":
        print(f"Error fetching runs: {result['runsOrError']['message']}")
    else:
        print(f"Unexpected result: {result}")

except Exception as e:
    print(f"An error occurred: {e}")