{"record":{"id":"b4a0d07b8631b20a","repo":"apache/iceberg","slug":"failed-to-load-catalog","errorCode":null,"errorMessage":"Failed to load catalog: {}","messagePattern":"Failed to load catalog: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java","lineNumber":817,"sourceCode":"  public static CatalogAndIdentifier catalogAndIdentifier(\n      SparkSession spark, List<String> nameParts, CatalogPlugin defaultCatalog) {\n    CatalogManager catalogManager = spark.sessionState().catalogManager();\n\n    String[] currentNamespace;\n    if (defaultCatalog.equals(catalogManager.currentCatalog())) {\n      currentNamespace = catalogManager.currentNamespace();\n    } else {\n      currentNamespace = defaultCatalog.defaultNamespace();\n    }\n\n    Pair<CatalogPlugin, Identifier> catalogIdentifier =\n        SparkUtil.catalogAndIdentifier(\n            nameParts,\n            catalogName -> {\n              try {\n                return catalogManager.catalog(catalogName);\n              } catch (Exception e) {\n                LOG.warn(\"Failed to load catalog: {}\", catalogName, e);\n                return null;\n              }\n            },\n            Identifier::of,\n            defaultCatalog,\n            currentNamespace);\n    return new CatalogAndIdentifier(catalogIdentifier);\n  }\n\n  private static TableCatalog asTableCatalog(CatalogPlugin catalog) {\n    if (catalog instanceof TableCatalog) {\n      return (TableCatalog) catalog;\n    }\n\n    throw new IllegalArgumentException(\n        String.format(\n            \"Cannot use catalog %s(%s): not a TableCatalog\",\n            catalog.name(), catalog.getClass().getName()));","sourceCodeStart":799,"sourceCodeEnd":835,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java#L799-L835","documentation":"Spark3Util resolves a possibly catalog-qualified identifier. When the CatalogManager's named catalog cannot be loaded (its plugin class fails to instantiate/configure), this warning is logged and null is returned so identifier resolution can try other candidates or fall back to the default catalog.","triggerScenarios":"Resolving table identifiers like myCatalog.db.table (via Spark3Util / catalogAndIdentifier) where catalog 'myCatalog' is registered in Spark conf but its implementation class is missing or misconfigured — the catalog load throws and is swallowed with this warning.","commonSituations":"Typo in catalog implementation class name; missing connector JAR on the classpath; bad catalog options (wrong warehouse URI, missing credentials); using a catalog name that was removed from the config.","solutions":["Read the logged exception to see why the catalog failed to load (ClassNotFound vs config error).","Fix spark.sql.catalog.<name> properties: correct implementation class, warehouse, and credentials.","Ensure the catalog's JAR (e.g. hive-metastore, aws-bundle, nessie) is on the Spark classpath.","Use the fully qualified identifier with a valid catalog or fix the default catalog config."],"exampleFix":"// before\nspark.conf.set(\"spark.sql.catalog.myCat\", \"org.apache.iceberg.shaded.Whatever\")\n\n// after\nspark.conf.set(\"spark.sql.catalog.myCat\", \"org.apache.iceberg.spark.SparkCatalog\")\nspark.conf.set(\"spark.sql.catalog.myCat.type\", \"hadoop\")\nspark.conf.set(\"spark.sql.catalog.myCat.warehouse\", \"s3://bucket/warehouse\")","handlingStrategy":"validation","validationCode":"// Pre-validate that a named catalog loads before resolving identifiers\ntry {\n  CatalogPlugin c = catalogManager.catalog(\"myCat\");\n} catch (Exception e) {\n  throw new IllegalArgumentException(\"Catalog myCat misconfigured: \" + e.getMessage(), e);\n}\nString impl = spark.conf().get(\"spark.sql.catalog.myCat\", null);\nPreconditions.checkArgument(impl != null, \"spark.sql.catalog.myCat must be set\");","typeGuard":null,"tryCatchPattern":"try {\n  CatalogPlugin c = catalogManager.catalog(name);\n} catch (Exception e) {\n  LOG.warn(\"Failed to load catalog: {}\", name, e);\n  throw new IllegalArgumentException(\"Check spark.sql.catalog.\" + name + \".* settings\", e);\n}","preventionTips":["Set spark.sql.catalog.<name> implementation class explicitly","Ship the catalog's bundle JAR on the classpath","Validate warehouse URIs/credentials at startup","Use fully qualified catalog.db.table identifiers in SQL"],"tags":["spark","catalog","configuration","classpath"],"backgroundTag":"missing-config-value","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}