Package installation and validation can fail for many reasons. This guide maps common error messages and symptoms to their root causes and fixes.

Danger

Always validate in CREATED state first, then install in a dev environment. Never install a new or modified package directly in production. Many errors only surface at installation time (INSTALLED state), not during validation (VALIDATED state). A package that passes validation can still crash at runtime. Replicate to production only after successful dev installation.

Error Quick Reference

Error / SymptomRoot CauseSection
”Object reference not set to an instance of an object”Invalid template property (centerArea on objectDetail)Template Runtime Error
”Reference not found: {key}“Missing dependency or loader order issueMissing References
”isDeletable returns false”Stale version references in PkgAssetMappingDeletion Blocked
”Package validation failed”Multiple possible issuesGeneric Validation Failure
”Duplicate feature on SingleOnly constraint”Feature declared on multiple object typesDuplicate Feature
”Feature value is required”A declared feature has no value fieldMissing Feature Value
Blank component / missing dataMissing declarations or invalid keysSilent Rendering Failures
”has no node configuration”Object type declares a diagram but has no graph node configurationObject Does Not Appear in a Diagram
Search returns no resultsElasticsearch reindex not triggeredSearch Not Working
SPACE facet gets shorter after a backend upgradeUpgrade restored space-import scoping; stale documents remain indexedSpace Facet Lists Unbound Spaces After a Backend Upgrade
Objects not visible in catalogSpace permissions not recalculatedCatalog Visibility
Codetable filter matches nothingWrong field used in automation filterAutomation Filter Mismatch

Template Runtime Error

Error: Object reference not set to an instance of an object

The objectDetail template type supports area[] as its layout property. Using centerArea — valid on other template types — causes a null reference at runtime.

Fix: Replace centerArea with area and use tabs to organize content sections.

Warning

This error occurs at runtime, not during validation. The package installs without issues. The failure appears only when a user opens an object that uses the affected template.

{
  "templateType": "objectDetail",
  "area": [
    {
      "areaType": "tab",
      "components": [ ... ]
    }
  ]
}

Missing References

Error: Reference not found: {key}

Two root causes produce this error.

Cause A — Missing dependency package. The referenced asset belongs to a package that is not installed. Cross-package references use the {packageKey}#{assetKey} syntax. If the package identified by {packageKey} is not installed, the reference cannot resolve.

Fix: Install the dependency package before installing the package that references it. Verify the asset exists in the dependency by checking its package JSON.

Cause B — Loader order conflict. The referenced asset’s loader runs after the current asset’s loader. Both assets belong to installed packages, but the loader sequence prevents resolution at the point of reference.

Fix: Verify the asset types involved. If the referencing asset type loads before the referenced asset type, restructure the package to eliminate the cross-type reference, or move the referenced asset to a dependency package that installs first.

Deletion Blocked

Error: isDeletable returns false

The PkgAssetMapping table tracks which database entities belong to which package version. Stale entries — self-referencing mappings or orphaned records from incomplete uninstalls — block deletion.

Fix: Contact a system administrator to inspect and clean stale references in the PkgAssetMapping table. Before deleting, verify that no other installed packages depend on the one being removed.

Warning

Do not attempt to clean PkgAssetMapping entries manually through direct database access. Use the administration interface or contact support.

Generic Validation Failure

Error: Package validation failed

This error wraps one or more specific validation issues. The validation report contains the individual errors.

Fix:

  1. Open the validation report from the package management UI.
  2. Read each error from top to bottom.
  3. Address errors in order — some errors cascade from earlier failures.
  4. Re-validate after fixing each batch of errors.
Tip

When you validate a package version that combines a base package with applied patches, each issue can show a “Source: {packageKey}” caption below its message — for example, “Source: core” or “Source: patch_code_lists”. The caption names the package that contributed the affected asset. Use it to identify in what package the error is. For details on how patches resolve against a base package, see Patch Packages — Advanced Guide. If the source package can’t be resolved, the caption is omitted and the row displays as before.

Cascade pattern: a missing objectType causes downstream failures in attribute mappings, relation mappings, template references, and search index definitions that reference that object type.

Duplicate Feature

Error: Duplicate feature on SingleOnly constraint

A feature marked as SingleOnly can only be assigned to one object type across all installed packages. Declaring it on a second object type triggers this error.

Fix: Remove the feature from all but one object type. Check both the current package and its dependencies for conflicting declarations.

Common SingleOnly features include system-level flags that control global behaviors such as default catalog views and primary navigation targets.

Missing Feature Value

Error: Feature value is required

Every declared feature must include an explicit value. A feature written as { "key": "is_html" } without a value field fails validation. This applies to features on every asset type — attribute types, object types, relation types, user relation types, pages, and workflow states.

Fix: Add the value field to the feature. Boolean flags take true or false:

{ "key": "is_html", "value": true }
Warning

The value field became mandatory on every feature with version 2026.3. Ensure the field is present when editing packages from older versions.

Silent Rendering Failures

No error message appears. Components render blank, panels show no data, or icons are missing.

Ownership Panel Shows No Data

Cause: The object type declaration is missing userRelationTypes. The ownership panel component requires explicit user relation type declarations to know which roles to display.

Fix: Add the userRelationTypes property to the object type definition:

{
    "key": "my_object_type",
    "userRelationTypes": [
        {
            "key": "core_business_owner"
        },
        {
            "key": "core_steward"
        }
    ]
}

Component Area Is Blank

Cause: Missing or incorrect componentId on the component definition. Without a valid componentId, the rendering engine skips the component silently.

Fix: Verify every component in the template has a componentId that matches a registered component. Check spelling and package prefix.

Object Does Not Appear in a Diagram

Cause: The object type’s template declares a diagram for a graph metamodel — either inline or through a referenced shared component — but the object type has no node configuration for that metamodel. The diagram tab opens, yet the lineage and knowledge-graph sync procedures never create a node for the object, so it is missing from the canvas.

Hierarchy children inherit the problem. When a parent object type declares the diagram, every descendant type in the hierarchy is rendered on the same canvas and needs its own node configuration.

Package validation reports this as a warning, not an error, so installation still succeeds. Look for these messages in the validation result:

Object type [my_object_type] has a diagram configured for the graph metamodel
[core_data_lineage] in its template but has no node configuration
(graph.R_Graph_Object_Type) for that metamodel.

Object types [my_child_type] appear as hierarchy children of [my_parent_type],
whose template declares a diagram for the graph metamodel [core_data_lineage],
but have no node configuration (graph.R_Graph_Object_Type) for that metamodel.

Fix: Add graphDisplayLevels for the reported metamodel to every object type named in the warning:

{
    "key": "my_object_type",
    "graphDisplayLevels": [
        {
            "metamodelKey": "core_data_lineage",
            "displayLevelKey": "core_object"
        }
    ]
}

Pick the displayLevelKey that matches the object’s place in the diagram — for example core_database, core_database_schema, or core_column for database structures. List the available levels of a metamodel by inspecting its displayLevels in the package that defines it. For more information, see Graph Metamodels and graphDisplayLevels.

Tip

A diagram component with no metamodelKey renders in the built-in core_data_lineage metamodel, so the warning can name a metamodel your template never mentions by name.

Icon or Color Missing

Cause: The iconKey or colorKey references a key that does not exist in the core package or any installed package.

Fix: Verify the icon and color keys exist. List available keys by inspecting the core package’s codetable assets. Undefined keys render as blank — no error, no fallback.

Tip

Use browser developer tools to inspect blank areas. Missing components leave empty DOM containers that reveal the expected componentId in data attributes.

Search Not Working

Symptom: Search returns no results for objects created after package installation.

Cause: Package installation does not trigger an Elasticsearch reindex. New search indexes exist in the configuration but contain no indexed documents.

Fix: Navigate to Settings > Search and trigger a full reindex. Reindex duration depends on data volume.

Warning

This is the most common post-installation issue. Every package that defines or modifies searchIndexes requires a manual reindex after installation.

Space Facet Lists Unbound Spaces After a Backend Upgrade

Symptom: After upgrading the backend, a search index that is scoped to specific spaces shows a shorter SPACE facet than before: spaces that used to appear are gone. Before the upgrade, those same spaces showed up in the facet with a count of (1) even though nothing in the package configuration bound the index to them.

Cause: An index’s space scoping comes from the space-import rules created when a package asset sets spacePath: each rule binds the index to one space. A backend defect caused indexes to ignore this scoping when importing space documents. A space-bound index received a document for every active space in the installation, rather than only the spaces it was actually bound to. The upgrade fixes this: the facet now reflects only the spaces with a real binding. A rule that leaves both the space and the application unscoped is unaffected: it already meant “every space.”

The fix only stops new documents from flowing to unbound spaces going forward. It doesn’t remove documents that were already indexed under the old, unscoped behavior. Those stay searchable until reindexed.

Fix:

  1. After the upgrade, compare each space-scoped index’s SPACE facet against its actual space-import rules. Any space still listed but with no rule bound to it was only appearing because of the defect.
  2. For every space that legitimately belongs in the facet, verify it has a space-import rule. Add one if it’s missing.
  3. Trigger a one-off reindex of each affected index to clear the stale documents: POST /api/indexer/refresh-index/{indexEnumKey}.
  4. Re-check the facet after reindexing completes.
Warning

Reindexing here is required even when no bindings changed for a given index. Documents written while the defect was active aren’t cleaned up automatically. Only a manual reindex removes them.

Catalog Visibility

Symptom: New object types do not appear in the catalog for any user.

Cause: Space permissions are not recalculated automatically when new object types are added by package installation. Users lack the computed permissions to see the new types.

Fix: Navigate to Settings and trigger a space permissions recalculation. After recalculation completes, new object types appear in catalogs for users with appropriate access.

Automation Filter Mismatch

Symptom: An automation rule with a codetable filter condition never matches, even though matching objects exist.

Cause: The filter uses the label field (display text) instead of the value field (internal identifier). Automation filters evaluate against value.

Fix: Replace the label string with the corresponding value string in the automation filter condition:

{
    "filter": {
        "attributeKey": "priority",
        "operator": "equals",
        "value": "high"
    }
}

Use "high" (the internal value), not "High Priority" (the display label).

Post-Installation Checklist

Run through this checklist after every package installation:

  1. Verify the package version state is INSTALLED in the package management UI.
  2. Trigger an Elasticsearch reindex (Settings > Search).
  3. Recalculate space permissions (Settings).
  4. Clear the browser cache (Ctrl+Shift+R / Cmd+Shift+R).
  5. Test object creation for each new object type.
  6. Open one object of each type and verify the template renders all components.
  7. Verify search returns results for new object types.
  8. Test automation rules if the package configures any.

Prevention

These practices eliminate the most common installation failures:

  • Validate before installing. Run validation on every package version before attempting installation. Fix all validation errors.
  • Use componentId on all template components. Components without IDs cannot be patched and produce blank renders silently.
  • Declare userRelationTypes on object types that use ownership components. The ownership panel renders empty without these declarations.
  • Verify icon and color key existence. Check that iconKey and colorKey values reference keys defined in the core package or an installed dependency.
  • Install dependencies first. Cross-package references fail if the target package is not installed.
  • Trigger reindex after every installation. Make it a habit rather than a troubleshooting step.
Tip

Keep a test environment that mirrors production package state. Validate and install packages there before deploying to production. Most silent failures are environment-specific and surface only at runtime.