---
title: "Dynamic Fields Host Custom Field Troubleshooting"
slug: "dynamic-fields-host-custom-field-troubleshooting"
description: "Troubleshooting guide para criacao e registro de fields custom no host com @praxisui/dynamic-fields."
doc_type: "guide"
document_kind: "runbook"
component: "dynamic-fields"
category: "components"
audience:
  - "host"
  - "frontend"
  - "ops"
level: "advanced"
status: "active"
owner: "praxis-ui"
tags:
  - "dynamic-fields"
  - "troubleshooting"
  - "custom field"
  - "host"
order: 37
icon: "build"
toc: true
sidebar: true
search_boost: 1.05
reading_time: 12
estimated_setup_time: 20
version: "1.0"
related_docs:
  - "dynamic-fields-host-custom-field-guide"
  - "dynamic-fields-field-selection-guide"
  - "dynamic-fields-inventory"
keywords:
  - "field not render"
  - "controlType not registered"
  - "hot update"
  - "CVA error"
last_updated: "2026-03-07"
---

# Dynamic Fields Host Custom Field Troubleshooting

## Objetivo

Fornecer resposta operacional rapida para falhas comuns na extensao de fields custom no host.

## Resposta operacional

1. confirme o `controlType` do contrato;
2. confirme runtime registry e metadata registry;
3. confirme compatibilidade com Angular Forms;
4. confirme se a falha e estrutural ou apenas de metadata/hot update;
5. confirme escopo correto de providers.

## 1. Field nao renderiza

### Check

- o `controlType` do contrato bate com o id registrado?
- o `ENVIRONMENT_INITIALIZER` roda no root app?
- o import dinamico retorna o componente certo?

### Typical root cause

`ComponentRegistryService.register(...)` nao foi executado ou foi executado em escopo errado.

## 2. controlType nao registrado

### Symptom

O runtime loga que o componente nao esta registrado.

### Fix

- registre o `controlType` exato;
- evite drift entre `my-custom`, `myCustom` e `my-custom-field`;
- mantenha um id canônico e unificado.

## 3. Editor nao mostra nome ou icone

### Root cause

O componente foi registrado no runtime, mas nao no `ComponentMetadataRegistry`.

### Fix

Registre um `ComponentDocMeta` com `id` identico ao `controlType`.

## 4. Hot update nao aplica

### Check

- o componente expoe `setInputMetadata(metadata)`?
- ou mantem metadata em signal reativa?
- a mudanca foi estrutural (`controlType`, add/remove field) ou apenas comportamental?

### Important

Mudancas estruturais ainda podem exigir refresh do loader. Hot update otimiza principalmente mudancas comportamentais/validacao.

## 5. Erro de forms / CVA

### Symptom

- valor nao propaga;
- touched nao propaga;
- disabled nao sincroniza;
- Angular reclama de value accessor.

### Fix

- implemente `ControlValueAccessor`, ou
- aceite `[formControl]` corretamente;
- propague `writeValue`, `registerOnChange`, `registerOnTouched`, `setDisabledState`.

## 6. Alias / selectors em conflito

### Symptom

Um alias antigo aponta para componente inesperado.

### Fix

- revise `FieldSelectorRegistry` e base/overrides;
- use `providePraxisDynamicFieldsNoDefaults()` apenas quando realmente quiser substituir a base;
- evite colisao de alias entre bibliotecas internas do host.

## 7. Provider em escopo errado

### Root cause

`FIELD_SELECTOR_REGISTRY_DISABLE_DEFAULTS` ou inicializadores foram fornecidos em modulo lazy, mas o singleton efetivo nasceu no root.

### Fix

Registre providers de governanca no root injector.

## 8. Tokens / tema quebram UX

### Symptom

- contraste ruim;
- largura inconsistente;
- estados de foco ilegiveis.

### Fix

- valide tokens M3 do host;
- garanta que tema e componentes compartilham o mesmo escopo;
- nao dependa de estilos locais fora dos contratos do design system.

## Final checklist

- `controlType` correto e unico.
- runtime registry ativo.
- metadata registry ativo.
- forms integration valida.
- hot update tratado.
- providers no root.
- tokens e tema validados.