mozilla

nsIScriptError

This article is in need of a technical review.

Represents JavaScript errors and warnings for use by the console service.
38.0.5
Introduced
Gecko 1.0
Inherits from: nsIConsoleMessage Last changed in Gecko 1.9 (Firefox 3)

Implemented by: @mozilla.org/scripterror;1. To create an instance, use:

var scriptError = Components.classes["@mozilla.org/scripterror;1"]
                  .createInstance(Components.interfaces.nsIScriptError);

Note: The nsIScriptError2 interface was merged into this interface in Gecko 12.0. Prior to that release, if you wanted to associate an outer window with a script error, you had to use nsIScriptError2 instead. That subclass offered the nsIScriptError.initWithWindowID() method for that purpose; that method is now available in this interface, however.

Method overview

void init(in wstring message, in wstring sourceName, in wstring sourceLine, in PRUint32 lineNumber, in PRUint32 columnNumber, in PRUint32 flags, in string category);
void initWithWindowID(in wstring message, in wstring sourceName, in wstring sourceLine, in PRUint32 lineNumber, in PRUint32 columnNumber, in PRUint32 flags, in string category, in unsigned long long innerWindowID);
AUTF8String toString();

Attributes

Attribute Type Description
category string A string indicating the category of error that occurred See Categories for a list. Read only.
columnNumber PRUint32 The column number where the error occurred. This is used to draw the arrow pointing to the problem character. Read only.
errorMessage AString

The error message in a string format without any context/line number information.

Note: nsIConsoleMessage.message will return the error formatted with file/line information.

Read only.
flags PRUint32 Flags; see Flag constants for a list. Read only.
innerWindowID unsigned long long The inner window ID with which the error is associated. This is zero if the error was initialized by calling nsIScriptError.init() instead of initWithWindowID(). Read only.
lineNumber PRUint32 The number of the line where the error occurred. Read only.
outerWindowID unsigned long long The window ID with which the error is associated. This is zero if the error was initialized by calling nsIScriptError.init() instead of initWithWindowID(). Read only.
sourceLine AString The line from the file specified by sourceName. You are responsible for providing that line. You may pass null if you are lazy; that will prevent showing the source line in JavaScript Console. Read only.
sourceName AString The URL of the file in which the error occurred. This will be a hyperlink in the JavaScript Console, so you should use a real URL. You may pass null if it's not applicable. Read only.
timeStamp long long Elapsed time, in milliseconds, from a platform-specific zero time to the time the message was created. Read only.

Flag constants

Constant Value Description
errorFlag 0x0 Error messages. A pseudo-flag for the default, error case.
warningFlag 0x1 Warning messages.
exceptionFlag 0x2 An exception was thrown for this case - exception-aware hosts can ignore this.
strictFlag 0x4 One of the flags declared in nsIScriptError.
infoFlag 0x8 Just a log message

Methods

init()

Initializes the object with information describing the error which occurred.

void init(
  in wstring message,
  in wstring sourceName,
  in wstring sourceLine,
  in PRUint32 lineNumber,
  in PRUint32 columnNumber,
  in PRUint32 flags,
  in string category
);
Parameters
message
The text of the message to add to the log.
sourceName
The URL of the file in which the error occurred. This will be a hyperlink in the JavaScript Console, so you should use a real URL. You may pass null if it's not applicable.
sourceLine
The line number in the source file on which the error occurred. You are responsible for providing that line. You may pass null if you are lazy; that will prevent showing the source line in JavaScript Console.
lineNumber
The number of the line where the error occurred.
columnNumber
The column number where the error occurred. This is used to draw an arrow pointing to the problem character.
flags
One of flags listed in Flag constants.
category
A string indicating what kind of code caused the message. There are quite a few category strings and they don't seem to be listed in a single place. See Categories for a partial list.

initWithWindowID()

Initializes the nsIScriptError object with the given inner window's ID.

Note: Prior to Gecko 12.0, this method was provided by the nsIScriptError2 interface, which has now been merged into this one.

void initWithWindowID(
  in wstring message,
  in wstring sourceName,
  in wstring sourceLine,
  in PRUint32 lineNumber,
  in PRUint32 columnNumber,
  in PRUint32 flags,
  in string category,
  in unsigned long long innerWindowID
);
Parameters
message
The text of the message to add to the log.
sourceName
The URL of the file in which the error occurred. This will be a hyperlink in the JavaScript Console, so you should use a real URL. You may pass null if it's not applicable.
sourceLine
The line number in the source file on which the error occurred. You are responsible for providing that line. You may pass null if you are lazy; that will prevent showing the source line in JavaScript Console.
lineNumber
The number of the line where the error occurred.
columnNumber
The column number where the error occurred. This is used to draw an arrow pointing to the problem character.
flags
One of the script error Flag constants
category
A string indicating what kind of code caused the message. There are quite a few category strings and they aren't listed in a single place, so you may need to search the Firefox code to find the one you want. See Categories for a partial list.
innerWindowID
The ID of the inner window associated with the error.

toString()

Outputs a string representing the error message described by the object.

AUTF8String toString();
Parameters

None.

Return value

A string representing the error message described by the nsIScriptError object.

Examples

Logging a message with additional information

In this example nsIScriptError, which implements nsIConsoleMessage, is used to log information to the console including information about the source file and line number of the error.

function myLogToConsole(aMessage, aSourceName, aSourceLine, aLineNumber, 
                        aColumnNumber, aFlags, aCategory)
{
  var consoleService = Components.classes["@mozilla.org/consoleservice;1"]
                                 .getService(Components.interfaces.nsIConsoleService);
  var scriptError = Components.classes["@mozilla.org/scripterror;1"]
                              .createInstance(Components.interfaces.nsIScriptError);
  scriptError.init(aMessage, aSourceName, aSourceLine, aLineNumber, 
                   aColumnNumber, aFlags, aCategory);
  consoleService.logMessage(scriptError);
}

Categories

There are a lot of categories, and they're not all maintained in a single list anywhere in the code. This is an attempt to group them together for reference. Note that these are strings. If you want to log an error at chrome level you should set a Category from the first section (leaving it empty might log it as content error). As Addon author I would recommend using "chrome javascript" for logging exceptions caused by addon code.

Categories the Web Console does not display

  • "XPConnect JavaScript"
  • "component javascript"
  • "chrome javascript"
  • "chrome registration"
  • "XBL"
  • "XBL Prototype Handler"
  • "XBL Content Sink"
  • "xbl javascript"
  • "FrameConstructor"

Categories the Web Console displays

  • "HUDConsole"
  • "CSS Parser"
  • "CSS Loader"
  • "content javascript"
  • "DOM Events"
  • "DOM:HTML"
  • "DOM Window"
  • "SVG"
  • "ImageMap"
  • "HTML"
  • "Canvas"
  • "DOM3 Load"
  • "DOM"
  • "malformed-xml"
  • "DOM Worker javascript"
  • "Mixed Content Blocker"
  • "CSP"
  • "Invalid HSTS Headers"
  • "Insecure Password Field"

See also

Document Tags and Contributors

Contributors to this page: Sheppy, trevorh, Wjjohnst, freddyb, wesj, AxelGrude, Sebastianz, Mw22, satyr, kscarfone
Last updated by: Sheppy,