Development Workflow & Troubleshooting

Local development workflow

After creating a new app using:

h_ app new

You can run the app in local development mode with:

h_ app dev

This starts a development version of your app from your local folder and continuously rebuilds it as you make changes.

To see those changes inside Hantera’s UI, you also need to enable development mode in the portal. When portal development mode is enabled, the portal loads your running dev app instead of the installed .hapk version.

This is why development mode is useful for troubleshooting:

• you can iterate on components, ingresses, rules, registry entries, and portal extension code
• and immediately verify the effect in the portal before packaging and installing a new version.

While development mode is enabled, it temporarily overrides the installed app version in the portal. To ship changes permanently, you still need to pack and install a new .hapk.

Troubleshooting

1. ACL Permission Errors

Symptoms:

• Component executes but fails at runtime
• Portal shows permission error
• Ingress returns 403 or unauthorized-style failure

Typical Causes:

• Missing actor permission
• Missing registry read permission
• Missing graph/* access

Example:

acl:
  - actors/order:create

But component also reads:

registry/apps/<appId>/settings/webhookSecret

Without:

- registry/apps/<appId>/settings/webhookSecret:read

Fix:

Add explicit registry or graph permission to the ingress ACL.

2. Structured Body Mismatch

Symptom:

• HTTP request hits ingress
• Component parameters are null
• Validation error
• "Missing parameter data"

Typical Causes:

Ingress body mode set to:

body:
  mode: structured

But incoming JSON didn’t match component param structure.

If component expects:

param order: {
  id: text
  cart: [...]
}

And the payload shape differs, parameter binding fails.

Fix:

• Match the JSON body to the declared param structure
• Or adjust the param contract to match the incoming JSON

3. Ingress component has parse errors

Symptoms:

• Ingress request returns 404
• Response body: Ingress component has parse errors

Typical Causes:

• The referenced .hrc or .hrl file contains invalid Filtrera syntax
• Incomplete let expression
• Mismatched braces or brackets
• Invalid keyword usage

If the component cannot be parsed, the ingress cannot invoke it.

Fix:

• Open the component file and correct the syntax error
• If you recently changed parameter names, confirm you reference declared params directly (for example order.get...``, not data.order...``)

4. Manifest Validation Errors

Symptoms:

• h_ app dev or h_ app pack fails
• CLI throws JSON deserialization error in Development mode
• Error mentions missing required properties

Example Error:

JSON deserialization for type 'AppManifestHttpIngress' 
was missing required properties including: 'properties'.

Typical Causes:

A required field in h_app.yaml is missing. For HTTP ingresses, the properties block is mandatory.

Fix:

Add required properties block:

ingresses:
  - id: orders
    componentId: components/orders.hrc
    type: http
    properties:
      route: /my-app/orders
      httpMethod: POST