Troubleshooting¶

Wikidata¶

Queries are slow, time out, or fail with HTTP 429¶

The Wikidata Query Service is a free, shared service with limits: each query may run for at most 60 seconds, and clients that send too much get 429 Too Many Requests and have to wait. During busy periods or outages, Wikimedia sometimes lowers these limits further.

• Use LIMIT while exploring, and start queries from specific items (wd:Q41264) rather than from whole classes (all paintings).
• Give the profile a timeout of up to 60 seconds; waiting longer doesn't help.
• Remember that every live block on a story page (SPARQL tables, IIIF queries, Graph Explorer clicks, embedded query views) is a request. A page with many of them, read by many people, adds up. Charts and maps don't query when they're read.
• Check the Wikidata Query Service status when everything fails at once.

Requests are blocked¶

Wikimedia requires a descriptive User-Agent with contact details. Set it in the profile:

headers:
  User-Agent: "my-shmarql-site/1.0 (https://example.org/; webmaster@example.org)"

or for all profiles with SPARQL_USER_AGENT.

The entity viewer is slow or times out¶

Use the simple construct_query and show_inverse_relations: false from the example profile. Famous items have a very large number of incoming links.

Profiles¶

Data stories¶

An embed says "The remote embed URL is not allowed"¶

The site of the URL isn't in nodes.embed.allowedOrigins. Add its origin (scheme and host, for example https://query.wikidata.org) to the file named by LODEON_CONFIG_PATH and restart SHMARQL. If the frame then stays empty, the other site may refuse to be framed (X-Frame-Options or frame-ancestors). That can only be changed by that site. If its page needs JavaScript, add allow-scripts to nodes.embed.sandbox.

A IIIF viewer stays empty¶

The browser loads manifests and images directly from the IIIF server. Open the browser's developer console: a CORS error means that server doesn't allow cross-origin requests, and nothing on the SHMARQL side can fix that. Use another server or manifest. Plain http:// manifests are refused as well; IIIF nodes need HTTPS (the editor refuses http:// URLs, and browsers block them on HTTPS sites).

A map or music block shows an error message¶

The JSON of the block didn't pass validation (for example a missing setting, an unknown tileLayerId, or coordinates out of range). Make the node in the editor and copy the block it writes. See The Markdown format.

The Graph Explorer shows only one or two neighbours on Wikidata¶

A known limitation: the expansion query fetches the neighbours' labels in every language, and on Wikidata those rows use up the query's row limit. Each click still adds a node, so you can explore step by step. Endpoints with labels in one or a few languages work as expected.

A Markdown page shows a live map where I wanted to show its source code¶

SHMARQL turns map, graph, embed and music blocks into HTML before the rest of the Markdown is processed. It also does that inside other code blocks. To show such a block as an example, write it in an HTML <pre><code> block with the backticks written as ```, as on The Markdown format.

The story editor¶