[tmpnet] Add optional stack traces to errors originating from tmpnet

[maru-ava]

Why this should be merged

Setting STACK_TRACE_ERRORS=1 will configure tmpnet to include stack traces with errors it originates. This is intended to aid in debugging by indicating not just the location of the failure but also the chain of callers.

Inspired by: golang/go#63358

How this works

• Add stacktrace package and ensure all tmpnet errors pass through its functions
• Said functions ensure that the stack trace is collected at the deepest point in the call chain for maximum traceability

How this was tested

• CI
• tmpnet default behavior

$ tmpnetctl start-network --node-count=0
Error: --node-count must be greater than 0 but got 0

• tmpnet with stacktraces

$ STACK_TRACE_ERRORS=1 tmpnetctl start-network --node-count=0
Error: --node-count must be greater than 0 but got 0
Stack trace:
/home/user/work/avalanchego/a_tmpnet-stacktrace/tests/fixture/tmpnet/tmpnetctl/main.go:76: main.main.func2
/home/user/go/pkg/mod/github.com/spf13/cobra@v1.8.1/command.go:985: github.com/spf13/cobra.(*Command).execute
/home/user/go/pkg/mod/github.com/spf13/cobra@v1.8.1/command.go:1117: github.com/spf13/cobra.(*Command).ExecuteC
/home/user/go/pkg/mod/github.com/spf13/cobra@v1.8.1/command.go:1041: github.com/spf13/cobra.(*Command).Execute
/home/user/work/avalanchego/a_tmpnet-reuse-state/tests/fixture/tmpnet/tmpnetctl/main.go:322: main.main
/home/user/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.23.9.linux-arm64/src/runtime/proc.go:272: runtime.main
/home/user/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.23.9.linux-arm64/src/runtime/asm_arm64.s:1223: runtime.goexit

Need to be documented in RELEASES.md?

N/A

[maru-ava]

Needed to reorder the args to ensure the error was last so that the stacktrace could be added to it.

[Copilot]

Pull Request Overview

Adds optional stacktraces to errors originating from tmpnet by introducing a new stacktrace package and integrating it throughout the tmpnet codebase. When STACK_TRACE_ERRORS=1 is set, errors will include stacktraces collected at the deepest point in the call chain for debugging assistance.

Key changes:

• Introduces a new tests/fixture/stacktrace package with New, Errorf, and Wrap functions
• Replaces standard error functions (fmt.Errorf, errors.New, err returns) with stacktrace equivalents throughout tmpnet
• Updates documentation to explain the stacktrace feature

Reviewed Changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 1 comment.

File	Description
tests/fixture/stacktrace/stacktrace.go	New stacktrace package implementing error wrapping with stack traces
tests/fixture/tmpnet/README.md	Documents the new stack trace error feature
Multiple tmpnet files	Replaces error handling with stacktrace equivalents

Comments suppressed due to low confidence (1)

tests/fixture/tmpnet/start_kind_cluster.go:1

• [nitpick] This TODO comment is unrelated to the stacktrace changes and appears to have been accidentally included in the diff. Consider removing it or addressing it in a separate PR.

// Copyright (C) 2019-2025, Ava Labs, Inc. All rights reserved.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[samliok]

wrapping the error in stacktrace is nice 👍 but don't you sort of get the same result if you fmt the error before returning it? ex.

return nil, stacktrace.Wrap(err)

vs

return nil, fmt.Errorf("failed to do something %w", err)

[joshua-kim]

but don't you sort of get the same result if you fmt the error before returning it? ex.

It's is similar, but you just get a long error string and have to reconstruct the call stack by searching for error messages (e.g failed to foo: failed to bar: failed to baz). It also doesn't handle deduping, so if you have similar error messages in multiple locations you might have some ambiguity. If you want a true stacktrace dump (like the ones that other languages support), to my understanding you just have to implement them yourself and this is considered idiomatic although it may look odd at first glance.

[joshua-kim]

I don't know if tmpnet has other env vars it supports, but should we prefix them with something like TMPNET_ or TMPNET_DEBUG_?

[maru-ava]

I intentionally avoided prefixing with TMPNET because it's not a tmpnet-specific thing. tmpnet is only the first adopter, but there's no reason for this library to be restricted to it (hence not putting it under tests/fixture/tmpnet).

[maru-ava]

Not that I think this env var is ideal, just that I think it's good enough for now.

[joshua-kim]

Do we have to export this type? It seems like we only use this type as the error interface downstream anyways.

[maru-ava]

I prefer to err on the side of exporting when it comes to library functionality in support of testing to minimize friction with downstream repos like coreth and subnet-evm.