Troubleshooting

The page and the plugin

What you see	What to do
AI resources is turned off by your administrator	The plugin is off. An administrator turns it on in Administration › Plugins: see Turn on AI resources.
No AI resources yet	No repository is published yet, or none was read yet. Add the annotations: see Publish your AI resources. On this page, Copy the example copies a catalog-info.yaml to start from.
No result among 9 resources (1 active criterion).	The search or a filter keeps nothing. Click Clear filters.
The search did not answer.	Click Retry. If it stays, tell your administrator.
The values of this filter could not be loaded.	Reload the page in a moment.
50 of 120 resources shown: narrow the search or the filters.	The page shows the first 50 resources. Type a word in Search AI resources or pick a filter.
AI resource not found.	The resource is not in the catalog (anymore). Go back to AI resources and search again.

The tab AI resources of a repository

Each message below appears under Problems on the tab AI resources of the component, and on the tab Repositories of Administration › AI resources.

What you see	What to do
Unknown annotation astrolabe.forgeit.tech/ai-skill-path. Did you mean astrolabe.forgeit.tech/ai-skills-path?	The name of the annotation is misspelled. Use the name it suggests.
Unknown annotation astrolabe.forgeit.tech/ai-tools-path: Astrolabe reads ai-skills-path, ai-agents-path, ai-rules-path, ai-runbooks-path.	Use one of the four names.
The folder playbooks (annotation astrolabe.forgeit.tech/ai-runbooks-path) does not exist on the default branch.	The path is wrong, or the folder is not pushed to the default branch yet. Fix the value of the annotation, or push the folder.
0 skill recognized in skills: a skill is a folder that contains a SKILL.md.	The path holds no skill. Check the path and that each skill folder holds a SKILL.md.
0 agent recognized in agents: an agent is a Markdown file with a name and a description.	Add name and description to the front matter of each agent file.
0 instructions file recognized in rules: recognized are AGENTS.md, CLAUDE.md, GEMINI.md, *.mdc, *.instructions.md, copilot-instructions.md and .claude/rules/*.md.	Point ai-rules-path at one of these files or at the folder that holds them.
0 runbook recognized in runbooks: a runbook is a Markdown file.	Put a .md file in the folder, or fix the path.
rules/pdf/SKILL.md is a skill: add its folder rules/pdf to astrolabe.forgeit.tech/ai-skills-path.	A file found under another kind. Do what the message says. The same message exists for an agent or a rule: add it to the annotation named in the message.
agents/broken.md has an invalid frontmatter at line 3: the YAML block between the two --- lines at the top of the file cannot be read. Look at that line: an unclosed bracket or quote is the usual cause.	Open the file, go to the line named, and close the bracket or the quote.
This repository has no owner (spec.owner): nothing is published.	Add spec.owner to the catalog-info.yaml, for example group:default/platform-team.
This repository has no backstage.io/source-location: Astrolabe cannot read it.	Register the repository from its URL: see Register a component.
Only url: source locations can be read.	The location of the component is not a url: one. Register it again from its URL.
The backstage.io/source-location of this repository points outside the repository it was registered from: Astrolabe only reads a component in its own repository.	Fix the annotation so it points to the repository that holds the catalog-info.yaml.
2500 files, limit 2000: the repository is skipped, its published resources are kept.	The repository is too big. Ask your administrator to raise Files per repository in Settings, or declare a smaller folder.
350 resources, limit 300: only the first 300 are published.	Ask your administrator to raise AI resources per repository, or split the repository.
skills/big/SKILL.md weighs 300000 bytes, limit 262144: the file is skipped.	Shorten the file, or ask your administrator to raise File size.
60000000 bytes to read, limit 52428800: the repository is skipped, its published resources are kept.	Ask your administrator to raise Repository size.
250 annotated repositories, limit 200: this one is not read.	Ask your administrator to raise Repositories read at most.
Not read again since 10/25/2026: the resources below are those of that reading.	The last reading failed. The cause is on the same tab.
This repository has never been read successfully.	The cause of the failure is on the same tab.
Not read yet: the next reading publishes its resources.	Click Read the repository again.
You are not allowed to refresh this component.	Your role does not let you read the repository again. Ask an administrator, or wait for the next reading.
A reading is already running: try again in a moment.	Wait, then click again.
The repository was not read again within 2 minutes: reload the page in a moment.	Reload the page.

When the reading fails

The state is Reading failed. The message starts with the host Astrolabe tried to reach, for example gitlab.exemple.com.

What you see	What to do
gitlab.exemple.com refuses the credentials (401): the token of the connection may be wrong or expired.	In Administration › Company connections, replace the token.
github.com refuses the credentials: the token of the connection may be wrong or expired. (no status)	Astrolabe could not even use the credentials: on GitHub, it is most often a GitHub App whose private key is not the content of the .pem file. In Administration › Company connections › GitHub Apps, paste the whole .pem file again, from -----BEGIN to -----END.
gitlab.exemple.com accepts the token but refuses access (403): give the token read access to this repository.	Give the token the right to read the repository.
gitlab.exemple.com answers « not found » (404): the repository moved, or the token cannot see it.	Check the address of the repository, and that the token sees it.
No server answers to the name gitlab.exemple.com: check the host of the connection.	Fix the host in Company connections.
gitlab.exemple.com does not answer in time: check its name and port.	Fix the name and the port of the connection.
gitlab.exemple.com refuses the connection: check the port, and that the server runs.	Check the port, and start the server.
Astrolabe does not trust the certificate of gitlab.exemple.com (often an internal one).	Tell the administrator of Astrolabe: the certificate must be trusted.
gitlab.exemple.com is too busy to answer (429): the next reading tries again.	Wait for the next reading, or click Run now later.
gitlab.exemple.com answers something unexpected.	Check the host and the API URL of the connection in Company connections.
Astrolabe could not read this repository on gitlab.exemple.com.	Read the other messages of the tab.

Click Fix the connection on the row to open the connection. Above its tokens, the page says which one reads the host, for example Astrolabe reads gitlab.exemple.com with the token « GitLab ». If it says No token of this connection is for gitlab.exemple.com: add one with « Add Token »., add a token for that host. The Host column gives the host of each token.

When a reading runs

What you see	What to do
A scan is already running: Astrolabe follows it.	Wait for the end: the table updates.
The scan stopped before reading the repositories: the catalog did not answer. Try again in a moment.	Click Run now again in a moment.
The scan did not finish within 2 minutes: the table updates when it does.	Wait: the table updates when the scan is over.
The state of the repositories could not be read.	Reload the page.
The catalog did not answer: the AI resources cannot be listed now.	Reload the page in a moment.

The file of a resource

What you see	What to do
The file could not be read: reload the page in a moment.	Reload the page.
This file cannot be shown: its name holds characters Astrolabe does not read (a space, an accent…).	Rename the file in the repository without space or accent.
Shown in part: the file is longer than what Astrolabe reads.	Read the end of the file in the repository.

The window Install

What you see	What to do
Codex does not read this resource: it is made for Claude Code, Cursor.	Pick a tool it is made for.
This file holds the instructions of a whole project.	Read it in the tab Content and copy what you need.
Astrolabe cannot compute an install command for gitlab.exemple.com yet.	Copy the files from the repository by hand.
Astrolabe gives no command for this resource: its path or address cannot be put safely in a command.	Copy the files from the repository by hand.
Astrolabe gives no command for this resource: its server answers over http and Astrolabe could not read the commit, so nothing proves the files would be the ones it read.	Copy the files from the repository by hand, or read the repository again.
Not pinned: Astrolabe could not read the commit. The command installs the current state of the default branch.	Read the repository again to pin the command to a commit.
Could not copy: select the text.	Select the command with the mouse and copy it.

The score

What you see	What to do
Not scored yet	Compass has not scored the resource yet. Click Read the repository again on the tab AI resources of the repository: it scores at once.
Score: not measured or Not measured	Compass could not measure the checks. Open the tab Compass of the resource and read the reason under Not measured.
Score unavailable: Compass did not answer.	Reload the page in a moment. If it stays, tell your administrator: the Compass plugin must run.
Astrolabe has not read this AI resource yet: read its repository again from the AI resources tab of the repository.	Do what it says.
The repository was read again, but Compass could not update the score: try again in a moment.	Click Read the repository again in a moment.
Some checks could not be measured: they count neither for nor against the score.	Read the reason under each Not measured check.

Still stuck?

Write to support@forgeit.fr with what you see on the screen.