PolyglotException (GraalVM SDK Java API Reference)

java.lang.Object
- java.lang.Throwable
- - java.lang.Exception
  - - java.lang.RuntimeException
    - - org.graalvm.polyglot.PolyglotException

All Implemented Interfaces:

Serializable
```
public final class PolyglotException
extends RuntimeException
```
A polyglot exception represents errors that contain Graal guest languages on the stack trace. In addition to the Java stack trace it also returns a polyglot stack trace. Methods like PolyglotException.printStackTrace() are implemented such that host and guest language stack traces are printed nicely.
A polyglot exception may have the following properties:
- Guest Exception: Is true if the exception was raised in guest language code.
- Host Exception: Is true if this exception was raised in host runtime code. This may happen if the polyglot runtime host runtime methods that throw an exception. The original host exception can be accessed using PolyglotException.asHostException().
- Cancelled: Is true if the execution got cancelled. The execution may be cancelled when closing a context, by a guest language intrinsic or by a tool, like the debugger.
- Exit: Is true if the execution exited. The guest language triggers exit events if the guest language code request to exit the VM. The exit status can be accessed using PolyglotException.getExitStatus().
- Syntax Error: Is true if the error represents a syntax error. For syntax errors a location may be available.
- Incomplete Source: Is true if this returns a syntax error that indicates that the source is incomplete.
- Resource exhausted: Is true if a resource limit e.g. the maximum memory was exhausted.
- Internal Error: Is true if an internal implementation error occurred in the polyglot runtime, the guest language or an instrument. It is not recommended to show such errors to the user in production. Please consider filing issues for internal implementation errors.
Since:

19.0

See Also:

Context, Value, Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

class PolyglotException.StackFrame
Represents a polyglot stack frame originating from a guest language or the host language Java.

Nested Classes
Modifier and Type	Class and Description
`class`	`PolyglotException.StackFrame` Represents a polyglot stack frame originating from a guest language or the host language Java.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Throwable`	`asHostException()` Returns the original Java host exception that caused this exception.
`boolean`	`equals(Object obj)`
`Throwable`	`fillInStackTrace()` Unsupported, `PolyglotException` instances are not writable therefore filling the stack trace has no effect for them.
`int`	`getExitStatus()` Returns the exit status if this exception indicates that the application was `exited`.
`Value`	`getGuestObject()` Returns an additional guest language object.
`String`	`getMessage()` Gets a user readable message for the polyglot exception.
`Iterable<PolyglotException.StackFrame>`	`getPolyglotStackTrace()` Provides programmatic access to the polyglot stack trace information printed by `PolyglotException.printStackTrace()`.
`SourceSection`	`getSourceLocation()` Gets a guest language source location of this error or `null` if no source location is available for this exception.
`StackTraceElement[]`	`getStackTrace()` Gets stack trace elements for Java and guest languages.
`int`	`hashCode()`
`boolean`	`isCancelled()` Returns `true` if the execution was cancelled.
`boolean`	`isExit()` Returns `true` if this exception is caused by an attempt of a guest language program to exit the application.
`boolean`	`isGuestException()` Returns `true` if this exception originates from a Graal guest language.
`boolean`	`isHostException()` Returns `true` if this exception originates from the Java host language.
`boolean`	`isIncompleteSource()` Returns `true` if this exception indicates a syntax error that is indicating that the syntax is incomplete.
`boolean`	`isInternalError()` Returns `true` if this exception was caused by an internal implementation error.
`boolean`	`isInterrupted()` Returns `true` if the current application thread was interrupted by an `InterruptedException`, or by calling `Context.interrupt(Duration)` from the host.
`boolean`	`isResourceExhausted()` Returns `true` if this exception indicates that a resource limit was exceeded, else `false`.
`boolean`	`isSyntaxError()` Returns `true` if this exception indicates a parser or syntax error.
`void`	`printStackTrace()` Prints host and guest language stack frames to the standard `error output`.
`void`	`printStackTrace(PrintStream s)` Prints host and guest language stack frames to specified print stream.
`void`	`printStackTrace(PrintWriter s)` Prints host and guest language stack frames to specified print writer.
`void`	`setStackTrace(StackTraceElement[] stackTrace)` Unsupported, `PolyglotException` instances are not writable therefore setting the stack trace has no effect for them.

Methods inherited from class java.lang.Throwable
addSuppressed, getCause, getLocalizedMessage, getSuppressed, initCause, toString

Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - printStackTrace
```
public void printStackTrace()
```
    Prints host and guest language stack frames to the standard error output.
    
    Overrides:
    
    printStackTrace in class Throwable
    
    Since:
    
    19.0
  - printStackTrace
```
public void printStackTrace(PrintStream s)
```
    Prints host and guest language stack frames to specified print stream.
    
    Overrides:
    
    printStackTrace in class Throwable
    
    Since:
    
    19.0
  - printStackTrace
```
public void printStackTrace(PrintWriter s)
```
    Prints host and guest language stack frames to specified print writer.
    
    Overrides:
    
    printStackTrace in class Throwable
    
    Since:
    
    19.0
  - fillInStackTrace
```
public Throwable fillInStackTrace()
```
    Unsupported, PolyglotException instances are not writable therefore filling the stack trace has no effect for them.
    
    Overrides:
    
    fillInStackTrace in class Throwable
    
    Since:
    
    19.0
  - getStackTrace
```
public StackTraceElement[] getStackTrace()
```
    Gets stack trace elements for Java and guest languages. For polyglot exceptions it recommended to use PolyglotException.getPolyglotStackTrace() as the guest language stack elements do not always fit the Java format for stack trace elements.
    
    Overrides:
    
    getStackTrace in class Throwable
    
    Since:
    
    19.0
  - getMessage
```
public String getMessage()
```
    Gets a user readable message for the polyglot exception. In case the exception is internal then the original java class name is included in the message. The message never returns null.
    
    Overrides:
    
    getMessage in class Throwable
    
    Since:
    
    19.0
  - getSourceLocation
```
public SourceSection getSourceLocation()
```
    Gets a guest language source location of this error or null if no source location is available for this exception.
    
    Since:
    
    19.0
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
    
    Since:
    
    19.0
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
    
    Since:
    
    19.0
  - setStackTrace
```
public void setStackTrace(StackTraceElement[] stackTrace)
```
    Unsupported, PolyglotException instances are not writable therefore setting the stack trace has no effect for them.
    
    Overrides:
    
    setStackTrace in class Throwable
    
    Since:
    
    19.0
  - getPolyglotStackTrace
```
public Iterable<PolyglotException.StackFrame> getPolyglotStackTrace()
```
    Provides programmatic access to the polyglot stack trace information printed by PolyglotException.printStackTrace(). Returns an array of stack trace elements, each representing one stack frame. The zeroth element of the array (assuming the array's length is non-zero) represents the top of the stack, which is the last invocation in the sequence. Typically, this is the point at which this throwable was created and thrown. The last element of the array (assuming the array's length is non-zero) represents the bottom of the stack, which is the first method invocation in the sequence.
    
    Since:
    
    19.0
    
    See Also:
    
    PolyglotException.StackFrame
  - isHostException
```
public boolean isHostException()
```
    Returns true if this exception originates from the Java host language. In such a case the first stack frame returns a host frame as zeroth element.
    
    Since:
    
    19.0
  - isGuestException
```
public boolean isGuestException()
```
    Returns true if this exception originates from a Graal guest language. In such a case the first stack frame returns a guest frame as zeroth element.
    
    Since:
    
    19.0
  - asHostException
```
public Throwable asHostException()
```
    Returns the original Java host exception that caused this exception. The original host exception contains a stack trace that is hardly interpretable by users as it contains details of the language implementation. The polyglot exception provides information for user-friendly error reporting with the polyglot stack trace.
    
    Throws:
    
    UnsupportedOperationException - if this exception is not a host exception. Call PolyglotException.isHostException() to ensure its originating from the host language.
    
    Since:
    
    19.0
  - isInternalError
```
public boolean isInternalError()
```
    Returns true if this exception was caused by an internal implementation error. These errors should be reported as bugs if observed. Internal error messages are typically hard to understand for guest language programmers and might contain implementation specific details that allows guest language implementers to debug the problem.
    
    Since:
    
    19.0
  - isResourceExhausted
```
public boolean isResourceExhausted()
```
    Returns true if this exception indicates that a resource limit was exceeded, else false. Resource limit exceeded errors may be raised for the following reasons:
    - The host runtime run out of memory or stack space. For example if host runtime throws OutOfMemoryError or StackOverflowError, then they will be translated to a PolyglotException that return true for PolyglotException.isResourceExhausted().
    - A configured resource limit was exceeded.
    - A runtime specific per context resource limit was exceeded. Depending on the host runtime implementation additional options to restrict the resource usage of a context may be specified using options.
    Resource limit exceptions may be originating from the host or guest. Resource limit exceeded errors are never internal, but may have caused the context to be cancelled such that it is no longer usable.
    Since:
    
    20.2
  - isCancelled
```
public boolean isCancelled()
```
    Returns true if the execution was cancelled. The execution can be cancelled by closing a context, if an instrument such as a debugger decides to cancel the current execution or if a resource limit was exceeded. The context that caused a cancel event becomes unusable, i.e. closed.
    
    Since:
    
    19.0
  - isInterrupted
```
public boolean isInterrupted()
```
    Returns true if the current application thread was interrupted by an InterruptedException, or by calling Context.interrupt(Duration) from the host.
    
    Since:
    
    20.3
  - isExit
```
public boolean isExit()
```
    Returns true if this exception is caused by an attempt of a guest language program to exit the application. The provided exit code can be accessed using PolyglotException.getExitStatus(). This can be the result of either the soft or the hard exit.
    
    Since:
    
    19.0
    
    See Also:
    
    Context
  - isSyntaxError
```
public boolean isSyntaxError()
```
    Returns true if this exception indicates a parser or syntax error. In such a case #get
    
    Since:
    
    19.0
  - isIncompleteSource
```
public boolean isIncompleteSource()
```
    Returns true if this exception indicates a syntax error that is indicating that the syntax is incomplete. This allows guest language programmers to find out if more code is expected from a given source. For example, an incomplete JavaScript program could look like this:
```
 function incompleteFunction(arg) {
 
```
    A shell might react to this exception and prompt for additional source code, if this method returns true.
    Since:
    
    19.0
  - getGuestObject
```
public Value getGuestObject()
```
    Returns an additional guest language object. Returns null if no exception object is available.
    
    Since:
    
    19.0
  - getExitStatus
```
public int getExitStatus()
```
    Returns the exit status if this exception indicates that the application was exited. The exit status is intended to be passed to System.exit(int). In case of hard exit the application can be configured to call System.exit(int) directly using Context.Builder.useSystemExit(boolean).
    
    Since:
    
    19.0
    
    See Also:
    
    Context

Class PolyglotException

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Throwable

Methods inherited from class java.lang.Object

Method Detail

printStackTrace

printStackTrace

printStackTrace

fillInStackTrace

getStackTrace

getMessage

getSourceLocation

equals

hashCode

setStackTrace

getPolyglotStackTrace

isHostException

isGuestException

asHostException

isInternalError

isResourceExhausted

isCancelled

isInterrupted

isExit

isSyntaxError

isIncompleteSource

getGuestObject

getExitStatus