Quando algo dá errado

Cada caso abaixo traz sintoma, causa provável e como resolver.

Encontrar a modelagem

“registry: há N modelagens e nenhuma marcada como active”

Causa. Existe mais de uma modelagem registrada e nada diz qual abrir.

Resolver. Escolha uma, de um destes jeitos:

cfour check --modelagem reservas      # só desta vez
cfour modelagem use reservas          # grava `active:` no cfour.yaml
export C4_MODELAGEM=reservas          # para a sessão

“modelagem desconhecida: …”

Causa. O identificador não está no cfour.yaml.

Resolver. cfour modelagem list mostra os registrados.

Um comando não acha nada, e você está no repositório certo

Causa. Não há cfour.yaml acima do diretório atual — a ferramenta sobe a árvore até achar um, e para aí.

Resolver. cfour init na raiz do repositório, ou aponte uma árvore avulsa com cfour check --root ./caminho/model.

O modelo não valida

“referência inexistente …”

Causa. Um parent, from, to, scope, subject, target ou um seletor ref aponta para uma caixa que não existe — quase sempre um erro de digitação, ou uma referência sem barra tentando alcançar outro projeto.

Resolver. Lembre da regra: sem barra procura o projeto que declara e depois shared/. Para atravessar projeto, qualifique: reservas/api.

cfour find api           # confere como a caixa se chama de verdade

“elemento duplicado: …”

Causa. Dois documentos declaram o mesmo identificador no mesmo projeto. A mensagem diz em qual arquivo o primeiro foi declarado.

Resolver. Renomeie um dos dois, ou mova-o para outro projeto.

“id inválido …”

Causa. O identificador tem um caractere que o formato não aceita. São permitidos letras, números, ponto, hífen e sublinhado, começando com letra ou número. A barra é reservada — ela separa projeto de identificador.

“ciclo de contenção: …”

Causa. Um parent fecha um laço: A é filho de B, que é filho de A.

Resolver. Quebre o laço. Enquanto ele existir, os membros são tratados como raiz — ou seja, aparecem como sistemas.

“YAML inválido: …”

Causa. Indentação, dois-pontos dentro de um valor sem aspas, ou tabulação.

Resolver. Cerque com aspas todo valor que contenha : ou comece com um caractere especial. Nunca use tabulação em YAML.

O desenho não é o esperado

O diagrama aparece vazio

Sintoma. O cfour check avisa: “o diagrama X não desenha nenhuma caixa”.

Causa. Nenhum seletor casou. Um tag: escrito errado, um scope para uma caixa sem filhos, ou um where que filtrou tudo.

Resolver.

cfour diagram show <id> --resolved

Ele diz o que entrou e por quê — e, quando nada entrou, mostra os seletores que você escreveu para você compará-los com o modelo.

Uma caixa que deveria aparecer não aparece

Causa mais comum. O scope mostra apenas os filhos diretos. Um neto não entra.

Resolver. Use include: [{descendants: <caixa>}], com depth se quiser limitar.

Segunda causa. Um exclude ou um where a tirou.

Duas setas paralelas entre as mesmas caixas

Causa. A mesma integração foi declarada em dois níveis: api → banco e repositorio → banco. O diagrama de containers desenha a declarada e a derivada.

Resolver. Apague a versão mais geral. Uma seta é escrita uma vez, no nível mais fino que você conhece — veja Relações.

“X tem N caixas dentro e nenhum diagrama”

Causa. Você criou filhos e não criou o diagrama que os mostra. O leitor nunca inventa uma visão, então aquele conteúdo existe no modelo e ninguém consegue vê-lo.

Resolver. Escreva o diagrama:

cfour diagram add containers --scope <a-caixa> --level container --relations auto

“groupBy: tag:… não existe mais”

Causa. Agrupar exige valor único, e uma caixa pode ter várias etiquetas.

Resolver. Agrupe por metadado (groupBy: meta.<chave>), ou escreva os grupos à mão com match: {tag: ...}. Veja Grupos.

Um passo do fluxo aparece marcado

Sintoma. O aviso diz “usa uma seta não declarada”.

Causa. O fluxo descreve uma conversa que o modelo não declara. Isso pode ser a resposta certa: o fluxo acabou de encontrar um buraco na estrutura.

Resolver. Ou declare a relação, ou aceite a marca. Três casos nunca avisam: contenção, chamada de uma caixa para ela mesma, e a resposta a uma seta declarada.

Autenticação e publicação

“nenhuma chave guardada”

Resolver.

cfour login --key c4_xxxxxxxx_yyyyyyyyyyyy    # na sua máquina
export CFOUR_KEY=c4_...                        # em CI

O push foi para o repositório errado

Causa. Uma máquina com várias chaves usou a chave padrão, e não a deste repositório.

Resolver.

cfour keys          # qual vale aqui, e por quê
cfour use <perfil>  # liga este repositório a outra chave

O vínculo usa o campo id: do cfour.yaml. Se o seu registro não tem esse campo, o cfour login o acrescenta.

“publicar em ‘main’ exige admin nesta organização”

Causa. A ref padrão é do admin.

Resolver. Publique em outra ref — o preview vale para qualquer membro — ou peça a um admin.

cfour push --ref minha-branch

“‘main’ foi publicada por outra pessoa”

Causa. Outra pessoa publicou naquela ref, e a plataforma recusa sobrescrever o trabalho dela.

Resolver. Publique em outra ref, ou peça a um admin — um admin passa.

“esta chave de publicação vence em N dia(s)”

Causa. Toda chave vence. O aviso aparece nos 14 dias anteriores.

Resolver. Gere outra na tela do repositório, troque o segredo onde ela é usada, e revogue a antiga.

“a chave pertence a quem não é mais membro desta organização”

Causa. Quem criou a chave foi removido.

Resolver. Gere uma chave nova, com uma pessoa que seja membro.

“este repositório é privado: publicar nele exige admin”

Causa. O repositório virou privado, e isso revoga também a escrita de quem não é admin.

“não foi possível determinar a ref”

Causa. HEAD destacado — comum em CI — ou fora de um repositório Git.

Resolver. cfour push --ref <nome>.

“nenhuma modelagem para publicar”

Causa. Nenhuma está com status: active, ou todas moram fora do repositório.

Resolver. A saída diz o motivo de cada uma pulada. --all inclui as puladas por status; uma modelagem fora do repositório nunca é publicada.

“bundle grande demais” ou “passaria de 10 MB publicados”

Resolver. Remova uma ref antiga pela tela do repositório. Um preview expira sozinho em 30 dias. Veja Limites.

O leitor local

“host não autorizado” ou “origem não autorizada” (403)

Causa. O cfour serve confere Host e Origin em toda requisição de dados, contra reassociação de DNS e requisição forjada.

Resolver. Abra pelo endereço que ele imprimiu. Para expor na rede, use --host <endereço> — o endereço passado passa a ser aceito.

“o viewer não foi encontrado em …”

Causa. A ferramenta está sendo executada a partir do repositório de desenvolvimento, sem o leitor construído.

Resolver. Instale pelo npm (npm i -g cfour-cli); o pacote traz o leitor dentro.

O desenho não mudou depois de salvar o YAML

Resolver. Recarregue a página. Se persistir, rode cfour check: um erro de carregamento mantém a versão anterior.

Servidor MCP

O cliente diz que não suporta registro dinâmico de cliente

Causa. É verdade: o servidor não faz registro dinâmico, e o client_id tem de chegar por configuração.

Resolver. Passe o client_id e a porta de retorno explicitamente — veja O servidor MCP.

O login falha com erro de endereço de retorno

Causa. O servidor de autorização casa a URL de retorno exata: esquema, host, porta e caminho. Um cliente que abra o laço local numa porta aleatória não conecta.

Resolver. Fixe a porta em 33418.

A busca não acha nada, e você sabe que existe

Causa provável. O vocabulário. Filtrar por risco numa modelagem que usa risk devolve zero, e zero parece uma resposta.

Resolver. Chame cfour_facets antes de filtrar. Ela lista as etiquetas, as chaves de metadado e os tipos de nota que existem ali.

Segunda causa. A modelagem não está indexada — porque passou do teto de indexação, ou porque a publicação foi agora. cfour_catalog diz o estado de cada uma, e toda resposta carrega a procedência.

“este recorte tem mais de 10.000 itens indexados”

Resolver. Informe repo ou modelagem na chamada.

Nada acima resolveu

cfour check --json          # o relatório inteiro, estruturado
cfour check --inventory     # + o inventário do modelo
cfour help formato          # as regras do formato, offline