> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot report access and execution

> Separate login, target addressing, report permissions, parameter errors, and incomplete execution.

Identify which step failed before retrying. Successful login confirms your credentials; it does not confirm permission to view a report.

| Symptom                                                 | What to check                                                                                                                                                      |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Login fails                                             | Verify the supplied host, exact username, password, and login signature construction.                                                                              |
| A previously working session fails                      | Check the JWT expiry and obtain a new session.                                                                                                                     |
| Presence probe is denied                                | Ask your provider to approve the presence subscription from your account to the report target.                                                                     |
| The target is unavailable                               | Verify the Reports JID with your provider and resolve its current full JID again.                                                                                  |
| `Source not found.`                                     | Check the target and whether this account can view the `Reports` data source. This response can mean the source is hidden by authorization.                        |
| Discovery returns `[]`                                  | Confirm the intended report is loaded on this target and visible to this account. Preserve a query failure as an error rather than converting it to an empty list. |
| JavaScript discovery is empty but HTTP returns one node | The current helper assumes a node array. Use the backend sample or normalize the underlying single-node response.                                                  |
| A selected report is missing                            | Refresh discovery and use its exact report ID, including spaces and path separators.                                                                               |
| Parameter submission fails                              | Fetch a fresh form and check field names, required values, options, hidden fields, and validation rules.                                                           |
| Execution is accepted but never completes               | Check browser events or the backend message consumer. Ensure another consumer is not taking the progress messages.                                                 |
| `queryAborted` or helper `HasErrors`                    | Treat collected output as partial and inspect messages and errors.                                                                                                 |

## Check the report target

The HTTP host identifies where you call the Agent API. The Reports JID identifies where reports are hosted.
The account username identifies who you are. The report ID identifies which report to run.
These values are not interchangeable.

For example, `neuron.example.com`, `client.reports`, `reports@neuron.example.com`, and `Client Reports\Monthly usage.rpx`
can all be needed for the same request sequence.

## Check source visibility

After login and presence resolution, ask which data sources the account can see.
Send `POST https://neuron.example.com/Agent/Xmpp/InformationQuery` using your actual host, application URL, JWT, and full Reports JID:

```http theme={null}
POST /Agent/Xmpp/InformationQuery HTTP/1.1
Host: neuron.example.com
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Content-Type: application/json
Accept: application/json

{
  "to": "reports@neuron.example.com/current-resource",
  "type": "get",
  "xml": "<getAllDataSources xmlns='urn:nf:iot:concentrator:1.0' xml:lang='en'/>"
}
```

Check HTTP success and `ok: true`, then inspect `Stanza.dataSources.dataSource`.
Normalize a single object to an array and look for `src: "Reports"`.
If it is absent, confirm the target and source permissions with your provider. Source visibility alone does not prove permission to execute every report.

This is the HTTP request behind `AgentAPI.Things.Concentrator.GetAllDataSources()` in the [original report walkthrough](https://lab.tagroot.io/Community/Post/Using_Agent_API_to_execute_reports_on_a_Neuron).

## Check the report's Execute command

Send another request to the same endpoint, using the same headers and the exact ID returned by discovery:

```http theme={null}
POST /Agent/Xmpp/InformationQuery HTTP/1.1
Host: neuron.example.com
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Content-Type: application/json
Accept: application/json

{
  "to": "reports@neuron.example.com/current-resource",
  "type": "get",
  "xml": "<getNodeCommands xmlns='urn:nf:iot:concentrator:1.0' xml:lang='en' src='Reports' id='Client Reports\\Monthly usage.rpx'/>"
}
```

After checking `ok`, inspect `Stanza.commands.command`, normalizing a single command to an array.
The report workflow needs an accessible command with `command: "Execute"` and `type: "Query"`.
If it is absent, ask your provider to check that report's executable commands and the account's permissions.
A `Query` returns asynchronous output; `Simple` and `Parametrized` commands use a different execution flow.

## Give your provider a useful failure report

Include the operation that failed, time, Reports JID, report ID, HTTP status, and sanitized `errorText` or helper error message.
For an execution problem, include the query ID and whether you received `queryStarted`, any records, and a terminal event.
Do not include passwords, JWTs, or report data that the recipient does not need.

## Provider checks

The report target must grant the calling account the report privileges it needs.
`Source.Reports.View` controls visibility of the Reports data source. Report nodes can require additional privileges.
Presence approval and report authorization are separate checks.

A role entry commonly used for report access is:

```text theme={null}
+Source\.Reports\..*
```

This grants matching report privileges; it does not restrict the account to one report file.
For access to one report, configure report-specific privileges and restrict the other reports as required.
Confirm the visible list using the actual client account.

If an XMPP account has the required role but only a matching local administrator user makes access work,
check that the server includes the XMPP account authorization fix. A duplicate administrator user is not required for report access.

## Retry deliberately

Refresh presence and discovery after a target reconnects or permissions change.
Avoid automatically executing a report again after a timeout: the first execution might still be running.
Preserve the original error instead of replacing every failure with “report not found.”