> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/scene-metadata/troubleshoot-scene-metadata.md).

# Troubleshoot scene metadata

Use this page to diagnose the most common problems with scene metadata in the Convai Unreal Engine plugin. Each section describes a symptom, its likely cause, and the fix.

### First-pass diagnostics

Before reading individual symptom sections, confirm the following. These three conditions account for most scene metadata problems:

1. **`ObjectEntry.Name` is non-empty** — objects with an empty name are refused and logged with `ConvaiObjectComponent on %s skipped: ObjectEntry.Name is empty`. Select the `UConvaiObjectComponent` in the Details panel and confirm the **`Name`** field is set.
2. **`bEnableActions` is `true` for connect-time actions and attention** — when `false`, `action_config` is not sent at `/connect`, and `SetObjectInAttention` has no effect. Check `EnvironmentData.bEnableActions` on the `UConvaiChatbotComponent`.
3. **Object added before or after the session starts** — any `Actor` with a `UConvaiObjectComponent` that is active before `StartSession()` is included in the initial snapshot; `Actor`s that spawn or are added after the session starts must use `AddObject` on the chatbot component to reach Convai.

{% hint style="info" %}
Open the **Output Log** in Unreal Engine and filter by `ConvaiSubsystemLog` for object registration and duplicate-name warnings, or `ConvaiObjectComponentLog` for tracked-property and gaze warnings.
{% endhint %}

### Character doesn't mention the object

**Symptom:** The character never references an `Actor` that has a `UConvaiObjectComponent`.

#### Empty name

**Cause:** Objects with an empty `ObjectEntry.Name` are refused by the subsystem. The component must have a non-empty name.

**Fix:** Open the `Actor`'s Details panel, select the `UConvaiObjectComponent`, and confirm that `ObjectEntry.Name` is set.

**Verify:** Enter Play mode and ask about the object by the name you set. If the answer does not use that object context, check the Output Log for the empty-name warning.

#### Runtime object added without an object component

**Cause:** A spawned `Actor` with a valid `UConvaiObjectComponent` registers itself at `BeginPlay`. If you manage environment entries manually without a `UConvaiObjectComponent`, the chatbot needs a matching `AddObject` call for the new entry.

**Fix:** Add a configured `UConvaiObjectComponent` to the spawned `Actor`, or call `AddObject` on the chatbot component after creating a manual `FConvaiObjectEntry`. Pass `bFlushImmediately = true` when the session is already active and the character needs the object in the next runtime update.

**Verify:** After calling `AddObject`, ask about the object and check whether the response uses the new object context.

#### Debounce delay

**Cause:** `AddObject` with `bFlushImmediately = false` queues the update in the debounce window. The update is not sent until the next environment flush.

**Fix:** Wait for the debounce window to flush, or use `bFlushImmediately = true` for time-sensitive runtime additions.

**Verify:** Confirm the chatbot session is in the `Connected` state before expecting a live `update-scene-metadata` push.

### Object reference resolves to the wrong actor

**Symptom:** The character references an object by an unexpected name, or navigation targets the wrong `Actor`.

**Cause:** Two `UConvaiObjectComponent` instances share the same `ObjectEntry.Name`. `UConvaiSubsystem` renames the duplicate automatically, but the renamed label may not match what the character was told.

**Fix:** Filter the Output Log by `ConvaiSubsystemLog` and look for a duplicate-name warning at `BeginPlay`. Ensure each `UConvaiObjectComponent` in the level has a unique `ObjectEntry.Name`.

**Verify:** After correcting the names, re-enter Play mode and confirm no duplicate-name warning appears for that `Actor`.

### Tracked property not updating

**Symptom:** The chatbot does not receive a new value when an `Actor` property changes at runtime.

#### Manual path entry

**Cause:** Typing `PropertyPath` by hand can fail if the path does not resolve against the `Actor` at runtime. The **Bind** button performs the resolution at authoring time and is the reliable method.

**Fix:** Remove the manually typed entry, click **Bind**, and select the property from the picker.

**Verify:** Change the property value in Play mode and filter the Output Log by `ConvaiObjectComponentLog` for tracked-property warnings. Alternatively, ask about the property and check whether the response uses the current value.

#### Unsupported property type

**Cause:** `TrackedProperties` supports leaf values such as `bool`, numeric types, `FString`, `FName`, `FText`, enums, whitelisted value structs, containers of supported leaf types, struct member paths, and pure parameterless functions that return a supported leaf value. Object references, class references, delegates, and multicast delegates are not supported; unsupported paths are skipped and warnings are logged.

**Fix:** Confirm the property type is supported. For complex state, expose a pure parameterless function that returns a supported leaf value, then bind to that function name.

**Verify:** After switching to a supported type or function, change the value in Play mode and check that no unsupported-path warning appears.

#### Path already tracked

**Cause:** `AddTrackedProperty` returns `false` if the path is already in the list. Duplicate paths are rejected.

**Fix:** Check the return value of `AddTrackedProperty`. Remove the existing entry before adding a new one with the same path.

**Verify:** Confirm `AddTrackedProperty` returns `true` after removing the duplicate, then change the property value and check for a dynamic context update.

#### Post-`BeginPlay` grace window

**Cause:** Changes that occur within approximately the first second after `BeginPlay` are forced to `EC_RunLLMOption::Never` regardless of the property setting. This prevents startup noise from making every chatbot react to initial game state.

**Fix:** This is expected behavior. If a property has a meaningful initial value, the session-start seed (which always uses `Never`) carries it correctly.

**Verify:** Change the property value more than one second after Play starts and check whether the update follows the configured `ShouldRespond` setting.

### Chatbot doesn't react to property changes

**Symptom:** A tracked property value changes at runtime but the character says nothing.

**Cause:** `ShouldRespond` is set to `Never`.

**Fix:** Change `ShouldRespond` to `Always` or `Auto` for properties whose changes you want the character to speak about.

**Verify:** Change the property value in Play mode more than one second after session start and confirm the update is no longer configured for silent delivery.

{% hint style="info" %}
The initial seed at session start always uses `EC_RunLLMOption::Never`. Later changes use the configured `ShouldRespond` after the post-`BeginPlay` grace window.
{% endhint %}

### Stale environment after runtime updates

**Symptom:** A runtime object update does not appear to affect the character's scene context.

#### Runtime update still pending

**Cause:** With `bFlushImmediately = false` (the default), updates wait in the debounce window. There may be a short delay before the update reaches Convai.

**Fix:** Wait for the debounce window to expire, or call `AddObject` with `bFlushImmediately = true` when immediacy is required.

**Verify:** After the debounce window expires (or after using `bFlushImmediately = true`), ask about the object and check whether the response uses the new object context.

### `Description` change not reflected mid-session

**Symptom:** Updating the description for an object that existed at session start does not change how the character understands that object.

**Cause:** If the object was already in `action_config` at `/connect`, its description in that frozen snapshot cannot be changed through `AddObject`. The live `update-scene-metadata` lane only accepts objects that are new to the session.

**Fix:** Call `StopSession` then `StartSession` to reconnect. The new session sends the updated description in a fresh `action_config`.

**Verify:** After reconnecting, ask about the object and check whether the response uses the updated description.

### Proximity state shows wrong description

**Symptom:** The chatbot receives unexpected or missing proximity information for an `Actor`.

#### No NavMesh

**Cause:** The proximity computation uses the Unreal Engine navigation system. If no NavMesh covers the area, reachability is marked as no walking path or unreachable.

**Fix:** Add a `NavMeshBoundsVolume` to the level and rebuild navigation (or enable dynamic navigation). Confirm the chatbot `Actor` has a nav agent configured.

**Verify:** Enable `bDebugDrawProximityPaths` on the `UConvaiObjectComponent` and enter Play mode. Green paths confirm the object is reachable, cyan indicates the chatbot is already at the target, and red indicates no valid walking path for the current query. If paths are red, check `NavMeshBoundsVolume` coverage and nav agent settings.

#### Diagnose with debug path drawing

**Cause:** Reachability problems are difficult to diagnose without seeing the navigation path query result.

**Fix:** Temporarily enable `bDebugDrawProximityPaths` on the `UConvaiObjectComponent` and enter Play mode. The plugin draws the navigation paths from each chatbot to this object. Disable the flag before shipping.

**Verify:** Green paths confirm reachability, cyan indicates the chatbot is already at the target, and red means the current query has no valid walking path.

### `SetObjectInAttention` has no effect

**Symptom:** Calling `SetObjectInAttention` from Blueprint does not change the chatbot's attention target.

**Cause:** `bEnableActions` is `false`. The attention system is part of the actions pipeline; when actions are disabled, attention updates have no effect.

**Fix:** Enable `bEnableActions` on the `UConvaiChatbotComponent`.

**Verify:** Restart the session and call `SetObjectInAttention` again. Confirm `AttentionSource` is `Explicit (Blueprint/C++)` on the chatbot component.

### Improving object descriptions

Convai receives the `Description` field as object context. Vague descriptions give the character less useful scene information.

| Avoid                   | Use instead                                                                                                      |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `"A fire extinguisher"` | `"Red ABC dry-chemical fire extinguisher mounted at eye level on the south wall, next to the emergency exit."`   |
| `"Door"`                | `"Heavy steel pressure door with a yellow warning stripe, leading to the decontamination chamber."`              |
| `"Machine"`             | `"Industrial hydraulic press at station 3, used for compressing sample containers. Safety guard is orange."`     |
| `"Box"`                 | `"Grey supply crate marked with a red cross, containing medical supplies, on the left shelf near the entrance."` |

Write descriptions from the perspective of what a knowledgeable guide or instructor would say. Include:

* Location relative to a landmark or room feature
* Visual identifiers — color, size, material
* Function or purpose where relevant

Keep each description concise enough to scan and specific enough to identify the object. The text is sent as object context, so include the details the character needs for conversation.

### Decision tree

Use this tree when the AI does not respond to scene objects after session start:

```
Is ObjectEntry.Name non-empty on the UConvaiObjectComponent?
├── No  → Set a unique, non-empty Name in the Details panel.
└── Yes → Does the spawned Actor have a valid UConvaiObjectComponent?
          ├── No  → Add the component, or call AddObject for a manual FConvaiObjectEntry.
          └── Yes → Is bEnableActions true on the chatbot's EnvironmentData when using connect-time actions or attention?
                    ├── No  → Enable bEnableActions.
                    └── Yes → Is the description specific and factual?
                              ├── No  → Rewrite with location, visual identifiers, and purpose.
                              └── Yes → Filter the Output Log by ConvaiSubsystemLog and check for duplicate-name warnings at BeginPlay.
```

### Next steps

{% content-ref url="/pages/ct7GZc4pJVR5cE2Nx02x" %}
[How scene metadata works](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/scene-metadata/how-scene-metadata-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/D7AS0tddjNnZ6oTWwtlC" %}
[Scene metadata component reference](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-component-reference.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/scene-metadata/troubleshoot-scene-metadata.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.