Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท java.lang

The StackWalker class

Reference for java.lang.StackWalker: walk the call stack lazily with streams, find the caller class, limit depth and compare with Throwable stack traces.

java.lang.StackWalker (Java 9) is the modern way to inspect the current thread's call stack. It replaces the habit of creating a Throwable or calling Thread.getStackTrace() just to see who called you. Instead of capturing the entire stack into an array, a walker hands you a stream of StackFrame objects that is produced lazily, so you only pay for the frames you actually look at.

Typical uses are logging frameworks finding the calling class and method, security and test utilities checking who invoked an API, and diagnostics that print a trimmed trace.

Java
StackWalker walker = StackWalker.getInstance();
walker.walk(frames -> frames.map(StackWalker.StackFrame::getMethodName).toList());

Try it

Java Method names of the current stack

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Limiting depth, filtering, and frame details

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public static StackWalker getInstance()
public static StackWalker getInstance(StackWalker.Option option)
public static StackWalker getInstance(Set<StackWalker.Option> options)
public static StackWalker getInstance(Set<StackWalker.Option> options, int estimateDepth)
Member Description
<T> T walk(Function<? super Stream<StackFrame>, ? extends T> function) Runs your function on a stream of frames, from the most recent caller outward, and returns its result. The stream is valid only inside the function.
void forEach(Consumer<? super StackFrame> action) Visits every frame.
Class<?> getCallerClass() The class of the caller of the method that invoked this; needs RETAIN_CLASS_REFERENCE. Throws IllegalCallerException if there is no caller.

StackWalker.StackFrame methods:

Method Description
getMethodName(), getClassName() Names of the executing method and its declaring class.
getLineNumber() Source line (negative if unavailable).
getFileName() Source file name, or null.
getMethodType() The method's parameter and return types (requires RETAIN_CLASS_REFERENCE).
getDeclaringClass() The Class object (requires RETAIN_CLASS_REFERENCE, else UnsupportedOperationException).
toStackTraceElement() Converts to the classic StackTraceElement.

Options (StackWalker.Option): RETAIN_CLASS_REFERENCE, SHOW_REFLECT_FRAMES, SHOW_HIDDEN_FRAMES. By default reflection and hidden frames (such as lambda bridge methods) are omitted.

Usage notes

  • Lazy and cheaper than new Throwable().getStackTrace() when you need only a few frames: the JVM fetches frames in batches as the stream consumes them.
  • The stream is not reusable. Do not let it escape the walk function; collect what you need into a list or value inside.
  • Frame 0 is the method that called walk. Use skip(1) to get its caller.
  • Class references are opt-in because exposing Class objects of callers is a security-sensitive capability. getCallerClass() replaces the unsupported sun.reflect.Reflection.getCallerClass().
  • Inlining and hidden frames: JIT inlining does not remove frames from reports, but lambdas and reflection frames may be hidden or shown depending on the options.
  • Line numbers depend on debug info. Classes compiled without -g may report negative numbers.
  • Output varies between launchers (source-file mode adds its own launcher frames below main), so avoid asserting on the complete trace.