Problemas do SAP BTP Cockpit: cinco falhas e como corrigi-las

Se o SAP BTP Cockpit está lhe devolvendo erros, provavelmente é uma de cinco coisas. Um 401 de uma service key quase sempre é a requisição OAuth, não as credenciais. Um Internal Server Error no Integration Suite costuma significar role collections ausentes ou uma sessão obsoleta. Links mortos vêm de boosters configurados antes de a subaccount mudar. Falhas de destination no CAP geralmente são divergência de nome ou um binding ausente. E um app que funcionava ontem numa conta trial pode ter perdido o banco de dados durante a noite. Este guia é para desenvolvedores e consultores de integração que trabalham em subaccounts do Cloud Foundry. A tabela de triagem abaixo diz o que verificar primeiro.

Na primeira vez que vi o banner vermelho de erro no SAP BTP Cockpit, achei que tinha feito algo errado. Link errado, sessão expirada.

Na terceira ou quarta vez, ficou claro que não era só comigo.

Nas semanas seguintes, mantive um caderno e anotei cada vez que algo quebrava. Internal Server Errors ao abrir o Integration Suite. Destinations que pareciam válidas e se recusavam a conectar. Apps que funcionavam ontem e travavam hoje. Os padrões foram aparecendo. Poucos estavam documentados em algum lugar útil, e o próprio Cockpit não dá quase nada com que trabalhar.

Sintoma	Causa mais provável	Verifique primeiro
401 Unauthorized ao chamar uma API com uma service key	Grant type errado, URL de token errada ou authorities ausentes	Decodifique o token e leia aud e scope
Internal Server Error ao abrir o Integration Suite	Role collections ausentes ou sessão obsoleta	Role collections no seu usuário e depois um logout completo
Booster ou tile abre uma página em branco ou errada	A subaccount mudou depois que o booster rodou	Navegue pela árvore do Cockpit em vez disso
App CAP: “destination not found” ou erros de autenticação	Divergência de nome, binding ausente, kind de OData errado	cds.requires e xs-app.json em comparação com o nome no Cockpit
O app funcionava ontem, trava hoje (trial)	A instância do HANA Cloud foi parada durante a noite	Status da instância de banco de dados no SAP HANA Cloud Central

O Cloud Foundry, o Kyma e o ambiente ABAP rodam na base multicloud da SAP, que é o padrão para novos clientes desde 2020. O ambiente Neo, mais antigo, recebe apenas atualizações de segurança e conformidade, e a SAP definiu o seu encerramento para 31 de dezembro de 2028. Quase todos os problemas abaixo são problemas do Cloud Foundry.

Duas mudanças de nome ainda confundem quem lê guias mais antigos. O SAP Launchpad service virou SAP Build Work Zone, standard edition, em janeiro de 2023. E muitos tiles e boosters foram reconstruídos conforme o SAP Build crescia, então capturas de tela de 2022 muitas vezes já não correspondem ao que você vê.

No RISE with SAP, o BTP normalmente chega como um direito de uso baseado em créditos dentro do contrato. O Cockpit é o mesmo. O que muda é quem, na sua organização, controla a global account, então descubra quem é essa pessoa antes de precisar de um novo direito de uso.

Você cria uma instância de serviço, gera uma service key, copia o client ID e o secret para o Postman, adiciona a URL do token e envia a requisição. 401. Sem nenhum detalhe.

Você copia o secret de novo. Continua falhando. O serviço está bem. O fluxo OAuth, não.

O que verificar, em ordem:

1. Grant type. O acesso técnico à maioria das APIs de serviço do BTP usa client_credentials. Defina-o explicitamente no Postman. Não confie no padrão.
2. URL do token. Pegue-a da service key. Algumas keys trazem um tokenurl; outras trazem a url do XSUAA, à qual você acrescenta /oauth/token. Nunca pegue emprestada a de outra subaccount.
3. Headers. Para uma chamada direta de token, envie Content-Type: application/x-www-form-urlencoded e Authorization: Basic <base64(clientid:clientsecret)>.
4. Authorities. Com client credentials, o token só carrega os scopes concedidos àquela instância de serviço. Se a API exige uma role que a instância não tem, você ainda recebe um token, e a API ainda diz não. Corrija nos parâmetros da instância (por exemplo, as roles em uma instância do plano de API do Integration Suite), não na requisição.
5. Audience. Se você tem um token e a API o rejeita, decodifique o token e leia a claim aud. Se ela não corresponder à API que você está chamando, você está usando uma key da instância de serviço errada.

Você abre o Integration Suite e recebe um banner vermelho de “Internal Server Error”. Sem log. Recarrega, troca de navegador, o mesmo resultado.

Costuma acontecer depois que o serviço ficou um tempo sem uso: aberto de manhã, deixado por algumas horas, usado de novo mais tarde. Os tópicos da comunidade SAP e a base de conhecimento apontam duas causas habituais: role collections ausentes e sessões obsoletas.

O que costuma resolver:

1. Verifique as role collections. Seu usuário precisa de Integration_Provisioner para configurar o tenant e das role collections PI_ relevantes (administrador, desenvolvedor de integração, especialista de negócio) para trabalhar nele. Atribua-as na subaccount, em Security.
2. Saia por completo. As mudanças de role só chegam à sua sessão depois de um novo login. Feche todas as abas do BTP e do Integration Suite, saia e entre de novo.
3. Limpe os cookies dos domínios do BTP se o erro sobreviver a um novo login. Um cookie de sessão obsoleto pode durar mais do que a sessão.
4. Use uma única sessão do Cockpit. Várias abas ou perfis de navegador na mesma subaccount causam conflitos de sessão que se parecem exatamente com esse erro.

O problema real é a visibilidade. O Cockpit não diz nada sobre o que falhou, então você acaba adivinhando. Em vez disso, percorra a lista em ordem. Para uma visão mais ampla de por que os programas de integração emperram, veja o meu artigo sobre atrasos na entrega do SAP Integration Suite.

Você clica em “Go to Application” e recebe uma tela em branco, uma página inicial genérica ou um redirecionamento que não faz sentido.

Isso segue padrões:

1. Os links de boosters quebram quando a configuração da subaccount muda depois que o booster rodou. O redirecionamento aponta para um lugar que já não existe.
2. Os tiles do Integration Suite às vezes funcionam, às vezes dão erro, às vezes estouram o tempo limite, geralmente pelos motivos de sessão descritos acima.
3. Os links do SAP Build Work Zone mostram “connection denied” quando a assinatura existe, mas o seu usuário não tem a role collection do site.
4. Várias abas ou perfis de navegador abrem links em contextos expirados.

O que funciona: navegar pela árvore do Cockpit (subaccount, depois Services, depois Instances and Subscriptions) e salvar nos favoritos as URLs diretas do Integration Suite, das destinations e do Work Zone. Use uma única sessão em um perfil de navegador limpo. Quando um link falha a cada três vezes, você para de confiar na plataforma e começa a montar soluções de contorno. Favoritos são a solução de contorno mais barata que existe. Se você ainda está se orientando, o meu passo a passo do BTP Cockpit cobre a navegação básica.

Você faz o deploy de um app CAP, configura uma destination no Cockpit e as requisições continuam falhando com “destination not found” ou erros de autenticação. A destination aparece na lista. O app está rodando. As mensagens de erro não apontam para lugar nenhum.

A documentação do CAP da SAP deixa claro como isso deve ser ligado: o serviço remoto é declarado em cds.requires, no package.json (ou .cdsrc.json), com um kind, e o nome da destination vai em credentials.destination. O app também precisa de bindings tanto com o serviço Destination quanto com o XSUAA. A maioria das falhas é uma ruptura em algum ponto dessa cadeia.

1. 01cds.requiresDeclara o serviço remoto, o seu kind e o nome da destination
2. 02Perfil de produçãoGuarda as credenciais da destination após o deploy
3. 03Service bindingsO app está vinculado ao Destination e ao XSUAA
4. 04Destination no CockpitMesmo nome de cds.requires e xs-app.json, inclusive maiúsculas e minúsculas
5. 05Serviço remotoodata-v2 para um serviço V2, odata para V4

As requisições chegam ao serviço remoto

Sintoma	Correção
A destination aparece na lista, mas o app não a encontra	Compare o nome em cds.requires e nas rotas de xs-app.json com o do Cockpit, caractere por caractere, inclusive maiúsculas e minúsculas
Funciona localmente, falha depois do deploy	Verifique se o perfil [production] realmente tem as credenciais da destination e se o app está vinculado ao Destination e ao XSUAA
O serviço OData V2 remoto retorna erros	Defina kind como odata-v2 para um serviço V2 e odata para V4. Use V4 sempre que os dois lados permitirem
Um app UI5 precisa de V2, mas o seu serviço CAP é V4	Adicione o plugin @cap-js-community/odata-v2-adapter. O antigo @sap/cds-odata-v2-adapter-proxy está obsoleto
A autenticação falha com credenciais válidas	Comece com OAuth2ClientCredentials ou BasicAuthentication. Use SAML ou propagação de principal somente quando o cenário exigir
Não tem certeza de que o destino é alcançável	Use “Check Connection” na destination, no Cockpit, antes de depurar o app

As equipes que lidam bem com isso mantêm uma lista de verificação curta de destinations para cada app. Não porque a configuração seja complexa. Mas porque uma suposição errada sobre nome, binding ou kind de OData falha em silêncio e leva muito mais tempo para ser encontrada do que para ser evitada.

Um app CAP que funcionava ontem agora trava. Nenhum erro. O Cockpit mostra que ele está rodando. Você o reinicia. Nada.

Verifique primeiro o banco de dados. O tutorial de trial do HANA Cloud da própria SAP afirma que as instâncias de free tier são paradas toda noite e precisam ser reiniciadas a cada dia de trabalho. A própria conta trial dura até 90 dias se você fizer login regularmente. O seu app está bem. O banco de dados dele é que está dormindo.

O que ajuda:

1. Reinicie a instância do HANA Cloud no SAP HANA Cloud Central antes de começar a depurar o código.
2. Use a CLI (cf apps, cf services) para ver o uso de memória e de serviços. A interface do Cockpit mostra bem menos.
3. Exclua as instâncias de serviço sem uso antes de criar novas. As cotas do trial valem para a conta inteira, não só para um app.
4. Mantenha as cargas de demonstração e de teste em subaccounts separadas.

Se você precisa de mais de um app e banco de dados rodando de forma confiável, ou de uptime estável para demonstrações, passe para uma conta produtiva. Os planos free tier em uma conta produtiva podem ser atualizados para pagos sem perder o seu trabalho, o que uma conta trial não permite.

Por que recebo um erro 401 com as credenciais da service key do SAP BTP, mesmo quando elas parecem corretas?

Quase sempre é a requisição OAuth, não as credenciais. As causas habituais são o grant type errado (use client_credentials para acesso técnico), uma URL de token que não corresponde à service key ou headers errados na chamada do token.

Se você recebe um token e a API ainda o rejeita, decodifique-o. Verifique se a claim aud corresponde à API e confira os scopes. Com client credentials, os scopes vêm das authorities concedidas à instância de serviço, então corrija as roles ausentes nos parâmetros da instância.

O que causa Internal Server Errors ao abrir o Integration Suite no BTP Cockpit?

Na maioria das vezes, role collections ausentes ou uma sessão obsoleta. Confirme que o seu usuário tem Integration_Provisioner e as role collections PI_ de que precisa. Depois feche todas as abas do BTP, saia e entre de novo, porque as novas roles só valem após um novo login.

Se persistir, limpe os cookies dos domínios do BTP e mantenha uma única sessão do Cockpit. Várias abas na mesma subaccount provocam o mesmo erro.

Por que o meu app CAP não consegue se conectar a uma destination que aparece corretamente no Cockpit?

Em geral, é uma divergência de nome. O nome da destination em cds.requires e nas rotas do xs-app.json precisa ser exatamente igual ao do Cockpit, inclusive maiúsculas e minúsculas.

Se o nome estiver certo, verifique se o app está vinculado tanto ao serviço Destination quanto ao XSUAA, se o perfil [production] carrega as credenciais e se o kind corresponde ao serviço remoto: odata-v2 para V2, odata para V4. Use “Check Connection” no Cockpit para confirmar que o destino é alcançável.

Por que o meu app no trial do SAP BTP para de funcionar durante a noite?

Nos planos trial e free tier, as instâncias do SAP HANA Cloud são paradas toda noite para economizar recursos. O seu app continua rodando, mas não alcança o banco de dados. Reinicie a instância no SAP HANA Cloud Central todo dia antes de trabalhar.

Use cf apps e cf services para conferir o uso de memória e de serviços, porque as cotas do trial são difíceis de ver no Cockpit. Exclua as instâncias sem uso antes de criar novas.

Por que os links dentro de boosters e tiles levam a páginas em branco?

Os links de boosters quebram quando a estrutura da subaccount muda depois que o booster rodou. O redirecionamento aponta para um local que já não existe ou que nunca foi totalmente configurado.

Navegue pela árvore do Cockpit e salve nos favoritos as URLs diretas do Integration Suite, das destinations e do SAP Build Work Zone. Não dependa da navegação gerada por boosters para nada que você use todo dia.

Quando devo passar de uma conta trial do BTP para um plano pago?

Quando os limites começam a custar tempo. Se você roda mais de um app ou banco de dados, ou precisa de uptime estável para demonstrações ou testes, o trial causa mais atrito do que economiza.

Os principais ganhos são estabilidade e uma visibilidade mais clara dos recursos, não funcionalidades novas. Uma conta produtiva com planos free tier é um bom meio-termo: você pode atualizá-los para pagos depois, sem reconstruir nada.