Error handling in scenes

This is about handling errors generated by scene file content, and not other types of errors (like errors interacting with the map or with signing in for example).

To qualify being in this section, an error or warning needs to be traceable to a line number (if not character) in a scene file.

Errors and warnings from Tangram

Tangram can fire events on errors and warnings. Tangram Play subscribes to these but needs to handle them depending on the type of error or warning it is. As of this writing these are all the error and warning events fired by Tangram and some additional information about them. These can change as new versions of Tangram add additional errors and warnings and Play needs to be able to flexibly handle new ones that do not have a specific handler.

Tangram API documentation: https://mapzen.com/documentation/tangram/Javascript-API/#error-and-warning

Errors

Tangram fires an error event when an unrecoverable error occurred while processing the scene. We get an Object with the following signature:

• type String — representing an "error code" of sorts.
• message String — text error message.
• error Object - the original error object thrown, from any source.
• url String - the url of the scene that was loaded.

These are the errors by type:

scene_import

errorObj = {
    type: 'scene_import',
    message: `Failed to import scene: ${error.url}`,
    error: // [?]
    url: // the scene that Tangram attempted to import
}

Thrown in scene_loader.js when an imported scene file cannot be loaded. As Tangram attempts to recursively collect imports, this error can be thrown more than once during a scene load for each import that fails. The url property on the error object is the URL of the scene that Tangram attempted to import, not the URL of the scene doing the import.

Note that we do automatically know where in the scene file a bad import statement occurs.

yaml

errorObj = {
    type: 'yaml',
    message: 'Error parsing scene YAML',
    error: { // A YAMLException thrown by js-yaml: https://github.com/nodeca/js-yaml/blob/master/lib/js-yaml/exception.js, inheriting from native Error object with the following additional properties:
        name: 'YAMLException'
        reason: // ?
        mark: { // An object representing the location of the error
            line: // Number of the line the error is located on, 0-indexed
            /* ... */
        }, 
        message: // A string
    },
    url: // the scene that generated the error
}

Thrown by scene.js when a scene file cannot be parsed by Tangram's internal YAML parser (a fork of the js-yaml library) during Tangram initialization.

undefined or scene (verify)

errorObj = {
    type: undefined or 'scene', // verify
    message: 'Error initializing scene',
    error: { // ?
        message: // inspect this for more info
    },
    url: // the scene that generated the error
}

Thrown by scene.js when an error occurs during Tangram initialization. This is the "fallback" error that is thrown with no additional information. Inspect the error object and the error.message property to see what else we can get from it. Common errors that occur here might be reported back to Tangram so that it can pass along more information effectively.

Warnings

Tangram fires a warning event when an recoverable issue occurred while processing the scene. We get an Object with the following signature:

• type String — indicating the scope of the issue (e.g. textures, sources, etc.)
• The rest of the object will have additional type-specific properties.

These are the warnings by type:

textures

errorObj = {
    type: 'textures',
    message: `Failed to load texture from ${this.source}` (or) `Failed to load texture because ${msg}`,
    error: // error object thrown by JavaScript. This is not present if the message is the second one above, so check to make sure it is present before attempting to access it.
    texture: // object containing options for the texture
}

Thrown by gl/texture.js when an error occurs while loading a texture.

sources

errorObj = {
    type: 'sources',
    message: `Could not create data source: ${e.message}`
    source: // string? the name of the source Tangram attempted to load
}

Thrown by scene.js when an error occurs while creating a data source from the sources block in the scene file. Note that the original error object is not passed along as the error property here.

Errors and warnings outside of Tangram

There are other errors and warnings that occur that Tangram does not catch (or is responsible for catching). In Tangram Play these errors and warnings should be collected and expressed in the same way since the user does not need to know what the source of the error is.

Handling errors

When Tangram hits an error, the remainder of the scene is no longer processed. It falls back to the last known good configuration if any, and displays that instead. In Tangram Play, this effect could occur: on a scene_import error, Tangram throws an error. If uncaught and undisplayed, the end user will not believe anything is wrong. When the user then does another stylistic change, e.g. update a color, Tangram will not update, having already failed on the import, and instead falling back to the scene configuration without the color change. This is exactly the scenario as described in issue #391.

Since we cannot (now) selectively tell Tangram to update a map but ignore bad imports, we need to indicate to the user that Tangram has stopped rendering updates, and that the error must be corrected before Tangram updates again.

To do

When do we stop updating? Errors are not recoverable; how do we recover from them? How to handle errors on page that have scrolled out of view?