Skip to content
AtsuraeDownload

Development sign-in

Only on a local server with DEV_AUTH. Enter any account name.

Errors and warnings

Atsurae checks every widget when it loads and every time its files change. Problems appear on the widget’s card in the Library and in Problems & Console in Customize Widgets.

  • Errors stop the widget from being shown. Its switch is disabled until they’re fixed.
  • Warnings don’t stop it, but usually point at a mistake.

In the messages below, elements[2] means the third element (counting starts at 0), and options[0] the first option.

Error. The file can’t be read as JSON. The rest of the message says where.

Fix: look for a missing or extra comma (JSON doesn’t allow a comma after the last item), a missing quote or brace, comments (JSON doesn’t allow //), or curly quotes (“ ”) from a word processor. An editor with JSON support highlights the spot.

Missing “field”. / Missing “field” in path.

Section titled “Missing “field”. / Missing “field” in path.”

Error. A required field is missing: formatVersion, id, name and elements at the top; key, label, kind and defaultValue in options; size in a font; file in a script.

Fix: add it. See widget.json.

“path” should be a number / text in quotes / true or false / a list in [ ] / an object in { }.

Section titled ““path” should be a number / text in quotes / true or false / a list in [ ] / an object in { }.”

Error. A field has the wrong type, like "size": "0.05" (text) instead of "size": 0.05 (number), or "shadow": "false" instead of false.

Fix: change the value’s type. Option defaultValues are the exception: they’re always text, so "defaultValue": "true" is right.

Error. A value is invalid, for example "type": "button" or "updateEvery": "hourly". The message explains what’s allowed.

Error. The file exists but can’t be opened, for example because of its permissions.

Error. A .atsuraewidget folder doesn’t contain a file named exactly widget.json at its top level.

Fix: check the file name (not Widget.json or widget.json.txt) and that it isn’t inside a subfolder.

This widget needs a newer version of Atsurae (format N). Update Atsurae to use it.

Section titled “This widget needs a newer version of Atsurae (format N). Update Atsurae to use it.”

Error. formatVersion is newer than this version of Atsurae understands.

Fix: update Atsurae, or if you wrote the widget, use format 2.

The id “X” can only use lowercase letters, numbers and dashes.

Section titled “The id “X” can only use lowercase letters, numbers and dashes.”

Error. Fix: use something like my-clock. It must start with a letter or number.

Another widget already uses the id “X” (file). Give this one a different id.

Section titled “Another widget already uses the id “X” (file). Give this one a different id.”

Error. Two widgets have the same id, or yours uses a built-in’s ID (day, date, time, now-playing, system, custom-text). Built-ins win, then whichever file sorts first.

Fix: change the id. A common cause is copying a widget to make a new one.

Error. name is empty.

Error. elements is an empty list.

Unknown field “X” in location; it’s ignored. Check the spelling.

Section titled “Unknown field “X” in location; it’s ignored. Check the spelling.”

Warning. A field Atsurae doesn’t know, usually a typo ("colour", "fontSize", "elemnts"), or a field in the wrong place (like size directly on a text element instead of in font).

Fix: check the spelling against the reference.

Warning. The token doesn’t exist, so it shows nothing. Usually a typo: {wether.temperature}, {Weekday}, {batery}.

Fix: see the token list. Tokens are case-sensitive. Option keys count as tokens only if you declared the option.

{script.X} in elements[N] needs a script. Add “script”: { “file”: “script.js” }.

Section titled “{script.X} in elements[N] needs a script. Add “script”: { “file”: “script.js” }.”

Warning. A {script.*} token is used, but the widget has no script.

Unknown modifier “|X” in elements[N]. Use upper, lower, percent or round.

Section titled “Unknown modifier “|X” in elements[N]. Use upper, lower, percent or round.”

Warning. Fix: use one of the four modifiers.

“visibleWhen” in elements[N] should be an option and value, like “use24Hour=true”, or a token, like “{track}”.

Section titled ““visibleWhen” in elements[N] should be an option and value, like “use24Hour=true”, or a token, like “{track}”.”

Warning. visibleWhen isn’t in a form Atsurae understands, or names an option the widget doesn’t declare.

Fix: declare the option, or check the spelling of its key. See Showing and hiding elements.

elements[N]: “X” in “field” isn’t a color. Use #RRGGBB or #RRGGBBAA.

Section titled “elements[N]: “X” in “field” isn’t a color. Use #RRGGBB or #RRGGBBAA.”

Warning. Color names like "red" and short forms like "#FFF" aren’t supported. The element uses its default color instead.

Fix: "#FF0000", or "#FFFFFF" for white.

Font “X” isn’t installed or in the widget’s fonts folder; the system font is used instead.

Section titled “Font “X” isn’t installed or in the widget’s fonts folder; the system font is used instead.”

Warning. Fix: use the font’s family name as shown in Font Book, install it, or put the .ttf/.otf file in the package’s fonts/ folder. See Fonts.

Error. A text element (an element without a type, or "type": "text") has no text.

Fix: add text, or set the right type if it’s meant to be an image, shape or progress bar.

elements[N] needs a “size”, like [0.1, 0.1].

Section titled “elements[N] needs a “size”, like [0.1, 0.1].”

Error. Images, shapes and progress bars need size: a list of two numbers, width and height.

elements[N] needs a “src”, the image’s path in the widget’s folder.

Section titled “elements[N] needs a “src”, the image’s path in the widget’s folder.”

Error. An image element has no src.

elements[N] uses an image, so the widget must be a folder (.atsuraewidget) with the image inside.

Section titled “elements[N] uses an image, so the widget must be a folder (.atsuraewidget) with the image inside.”

Error. A single-file widget can’t contain images. Fix: make it a package.

elements[N]: the image “X” isn’t in the widget’s folder.

Section titled “elements[N]: the image “X” isn’t in the widget’s folder.”

Error. Fix: check the path and file name, including capitalization and the extension (.png vs .PNG).

elements[N]: “shape” must be rect, circle or line.

Section titled “elements[N]: “shape” must be rect, circle or line.”

Error.

elements[N] needs a “value” from 0 to 1, like “{battery.level}”.

Section titled “elements[N] needs a “value” from 0 to 1, like “{battery.level}”.”

Error. A progress element has no value.

elements[N]: “style” must be bar or ring.

Section titled “elements[N]: “style” must be bar or ring.”

Error.

options[N] is a choice but has no “choices”.

Section titled “options[N] is a choice but has no “choices”.”

Error. Fix: add "choices": ["a", "b"].

The script “X” isn’t in the widget’s folder.

Section titled “The script “X” isn’t in the widget’s folder.”

Error. script.file names a file that doesn’t exist in the package.

A widget with a script must be a folder (.atsuraewidget) with the script inside.

Section titled “A widget with a script must be a folder (.atsuraewidget) with the script inside.”

Error. Fix: make it a package.

Error. The script threw an exception while loading or running, for example TypeError: undefined is not an object (evaluating ‘context.weather.temperature’) (line 4). The script stops until you save a change.

Fix: read the message and line number. The most common cause is using a value that’s null (like context.weather before the weather loads). See Debugging scripts.

The script has no update(context) function.

Section titled “The script has no update(context) function.”

Error. Fix: define function update(context) { … } at the top level of the script.

update() must return an object, like { greeting: “Hi” }.

Section titled “update() must return an object, like { greeting: “Hi” }.”

Error. update returned nothing, a string, a number, an array or a Promise. Fix: return { … }. Make sure every path through the function returns.

The script took too long (over 0.25 seconds) and was stopped.

Section titled “The script took too long (over 0.25 seconds) and was stopped.”

Error. Usually an endless loop (while (true), a for loop whose condition never changes), or very heavy work on every run.

Fix: check your loops. Compute expensive things once, at the top level, not in update.

These appear in Problems & Console for widgets that show weather.

Location access is off. Turn it on for Atsurae in System Settings ▸ Privacy & Security ▸ Location Services, or type a city in Atsurae Settings ▸ Weather.

Section titled “Location access is off. Turn it on for Atsurae in System Settings ▸ Privacy & Security ▸ Location Services, or type a city in Atsurae Settings ▸ Weather.”

Atsurae has no way to know where you are. Either fix works.

Atsurae couldn’t find “X”. Check the city in Settings ▸ Weather.

Section titled “Atsurae couldn’t find “X”. Check the city in Settings ▸ Weather.”

The city you typed couldn’t be found. Try adding the country: Springfield, Illinois.

Apple Weather isn’t available right now (…).

Section titled “Apple Weather isn’t available right now (…).”

The weather service couldn’t be reached, often because the Mac is offline. Atsurae tries again in 30 minutes.

The zip has no widget.json file, .atsuraewidget folder or .json file.

Choose an .atsuraewidget folder, a widget .json file or a .zip.

Section titled “Choose an .atsuraewidget folder, a widget .json file or a .zip.”

You tried to import something else.

Couldn’t unpack the widget (ditto exited with N).

Section titled “Couldn’t unpack the widget (ditto exited with N).”

The zip is damaged or isn’t a zip.

The widget has an error. Fix it first.

Built-in widgets and widgets from the community can’t be uploaded. Make a copy with a new id in your widgets folder if you’ve changed one substantially.

Widgets can be up to 10 MB zipped. Make the images smaller or remove unused files.

Section titled “Widgets can be up to 10 MB zipped. Make the images smaller or remove unused files.”

Shrink large images (a 4000-pixel photo is rarely needed) and remove files you don’t use.

Sharing widgets is part of the full version. Buy Atsurae to upload.

Section titled “Sharing widgets is part of the full version. Buy Atsurae to upload.”

Anyone can download widgets; uploading needs the full version.

Your account can’t share or report uploads anymore.

Section titled “Your account can’t share or report uploads anymore.”

A moderator banned the account from sharing, for the reason shown. You can still use Atsurae and everything you’ve downloaded.

Atsurae couldn’t draw a preview of this widget.

Section titled “Atsurae couldn’t draw a preview of this widget.”

The widget couldn’t be rendered for its picture. Check it shows correctly in Customize Widgets.