{"record":{"id":"65ea8c0b2137f2e7","repo":"apache/beam","slug":"failed-to-initialise-spanner-client-v","errorCode":null,"errorMessage":"failed to initialise Spanner client: %v","messagePattern":"failed to initialise Spanner client: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"sdks/go/pkg/beam/io/spannerio/common.go","lineNumber":63,"sourceCode":"}\n\nfunc (f *spannerFn) Setup(ctx context.Context) error {\n\tif f.client == nil {\n\t\tvar opts []option.ClientOption\n\n\t\t// Append emulator options assuming endpoint is local (for testing).\n\t\tif f.TestEndpoint != \"\" {\n\t\t\topts = []option.ClientOption{\n\t\t\t\toption.WithEndpoint(f.TestEndpoint),\n\t\t\t\toption.WithGRPCDialOption(grpc.WithTransportCredentials(insecure.NewCredentials())),\n\t\t\t\toption.WithoutAuthentication(),\n\t\t\t\tinternaloption.SkipDialSettingsValidation(),\n\t\t\t}\n\t\t}\n\n\t\tclient, err := spanner.NewClient(ctx, f.Database, opts...)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to initialise Spanner client: %v\", err)\n\t\t}\n\n\t\tf.client = client\n\t}\n\n\treturn nil\n}\n\nfunc (f *spannerFn) Teardown() {\n\tif f.client != nil {\n\t\tf.client.Close()\n\t}\n}\n","sourceCodeStart":45,"sourceCodeEnd":77,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/io/spannerio/common.go#L45-L77","documentation":"spannerio.Setup creates a Cloud Spanner client during pipeline setup; this error wraps any failure from spanner.NewClient (or its underlying spanner.NewClientWithConfig path). Since Setup runs once per worker before processing, a failure here stops the pipeline at startup with the underlying Spanner error appended.","triggerScenarios":"Running a Beam pipeline with the spannerio.Read/Write transform when spanner.NewClient fails: invalid database path format, missing/insufficient GCP credentials, project/database/instance does not exist, network egress blocked, or client creation timeout.","commonSituations":"Missing GOOGLE_APPLICATION_CREDENTIALS or default credentials on the worker; typo in projects/p/instances/i/databases/d path; Spanner API not enabled on the project; private-network runners with no route to spanner.googleapis.com.","solutions":["Read the wrapped %v cause and fix accordingly: usually credentials (run `gcloud auth application-default login` or provide service-account creds to workers).","Verify the database string exactly matches projects/<project>/instances/<instance>/databases/<db> and that the instance/database exist.","Enable the Spanner Admin/API on the GCP project and confirm the service account has roles/spanner.databaseUser.","Check network egress from the runner/workers to spanner.googleapis.com:443 (VPC firewall, NAT config).","Retry after fixing — the client is created in Setup, so any fix requires restarting the pipeline."],"exampleFix":"// before\nf.Database = \"my-instance/my-db\" // wrong format\n// failed to initialise Spanner client: ...\n\n// after\nf.Database = \"projects/my-project/instances/my-instance/databases/my-db\"","handlingStrategy":"validation","validationCode":"// Pre-flight checks before launching the pipeline:\nif !strings.HasPrefix(db, \"projects/\") {\n    return fmt.Errorf(\"invalid database path: %s\", db)\n}\ncreds, err := google.FindDefaultCredentials(ctx)\nif err != nil {\n    return fmt.Errorf(\"no GCP credentials found: %w\", err)\n}\n_ = creds","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always build the database path as projects/<proj>/instances/<inst>/databases/<db>.","Provision worker credentials explicitly (service account with roles/spanner.databaseUser).","Smoke-test spanner.NewClient in a small script before running the full pipeline.","Verify the Spanner API is enabled and network egress to spanner.googleapis.com is allowed."],"tags":["gcp","spanner","client-init","network","credentials"],"backgroundTag":"api-request-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}