Troubleshooting Package Issues

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

Error Quick Reference

Error / Symptom	Root Cause	Section
”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 issue	Missing References
”isDeletable returns false”	Stale version references in PkgAssetMapping	Deletion Blocked
”Package validation failed”	Multiple possible issues	Generic Validation Failure
”Duplicate feature on SingleOnly constraint”	Feature declared on multiple object types	Duplicate Feature
Blank component / missing data	Missing declarations or invalid keys	Silent Rendering Failures
Search returns no results	Elasticsearch reindex not triggered	Search Not Working
Objects not visible in catalog	Space permissions not recalculated	Catalog Visibility
Codetable filter matches nothing	Wrong field used in automation filter	Automation 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.

{
  "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.

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.

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.

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.

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.

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.

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.