These are the following most common problems that can occur during development, setting up or running the application. If you encounter further issues, feel free to add them and help other contributors during onboarding. Try to follow the same structure when explaining the steps and not include any personal information.

When: Running in debug mode

Error: /Users/lio/go/go1.23.4/bin/go tool test2json -t /private/var/folders/gt/nw97n8md6xd2kc0hzghr_4cr0000gn/T/dlvLauncher.sh /Applications/GoLand.app/Contents/plugins/go/lib/dlv/macarm/dlv --listen=127.0.0.1:54124 --headless=true --api-version=2 --check-go-version=false --only-same-user=false exec /private/var/folders/gt/.../T/GoLand/....test -- -test.v -test.paniconexit0 -ginkgo.v -ginkgo.trace ^C{"Time":"2025-03-10T16:33:42.689397+01:00","Action":"output","Output":"2025-03-10T16:33:42+01:00 error layer=debugger error loading binary \"/private/var/folders/gt/.../T/GoLand/....test\": error reading debug_info: decoding dwarf section info at offset 0xa1540f: DW_FORM_strx with no .debug_str_offsets section\n"} 2025-03-10T16:33:42+01:00 error layer=debugger could not patch runtime.mallogc: no type entry found, use 'types' for a list of valid types could not launch process: error reading debug_info: decoding dwarf section info at offset 0xa1540f: DW_FORM_strx with no .debug_str_offsets section

Explanation: The dlv version used is not compatible with your current Go version. Keep in mind that the version used by your IDE might be different from the one you are using.

Solution:

1. Make sure you have downloaded dlv and that it is under $GOPATH/bin. If not: go install github.com/go-delve/delve/cmd/dlv@master
2. Replace the version used by your IDE with the new one using a symlink:

cd /Applications/GoLand.app/Contents/plugins/go/lib/dlv/macarm/dlv mv dlv dlv.old ln -s $GOPATH/bin/dlv dlv 

When: During compilation (or test run) Error:

Failed to build github.com/hyperledger-labs/fabric-smart-client/cmd/fsccli: Error: exit status 1 Output: package github.com/hyperledger-labs/fabric-smart-client/cmd/fsccli	imports github.com/hyperledger-labs/fabric-smart-client/integration/nwo/cmd/artifactgen	imports github.com/hyperledger-labs/fabric-smart-client/integration	imports github.com/hyperledger-labs/fabric-smart-client/integration/nwo	imports github.com/hyperledger-labs/fabric-smart-client/integration/nwo/common/runner	imports github.com/onsi/gomega	imports github.com/onsi/gomega/matchers	imports golang.org/x/net/html/charset	imports golang.org/x/net/html	imports iter: build constraints exclude all Go files in /.../go/go1.22.6/src/iter 

Solution: Make sure you are using the correct Go version.

When: During integration test runs (using NWO) on macOS (observed on M1, version 15.3.1).

Error: Chaincode invocation fails due to connectivity issues, occasionally related to TLS.

[e][fabric.default-Org1.Org1_peer_0] 2025-03-06 20:13:50.990 IST 006f INFO [peer.chaincode.u5pgmb25djahtfcwslat2uwtri-Org1_peer_0.org1.example.com-token-chaincode-1cd4d59fb9532a25ab05275b954ef35d5f77fbbf928a94ed6e41643f9d9300be] func2 -> CC ID or CC address is empty... Running as usual... [e][fabric.default-Org1.Org1_peer_0] 2025-03-06 20:13:51.015 IST 0070 ERRO [core.comm] ServerHandshake -> Server TLS handshake failed in 19.4225ms with error read tcp 192.168.68.54:5133->192.168.68.54:50309: read: socket is not connected server=ChaincodeServer remoteaddress=192.168.68.54:50309 [e][fabric.default-Org1.Org1_peer_0] 2025-03-06 20:13:51.019 IST 0071 INFO [peer.chaincode.u5pgmb25djahtfcwslat2uwtri-Org1_peer_0.org1.example.com-token-chaincode-1cd4d59fb9532a25ab05275b954ef35d5f77fbbf928a94ed6e41643f9d9300be] func2 -> panic: cannot start chaincode: [[connection error: desc = "transport: authentication handshake failed: read tcp 192.168.5.15:40664->192.168.68.54:5133: read: connection reset by peer"]] 

Explanation: Connectivity issues occur because the built-in macOS firewall is blocking connections to the peer or orderer binaries.

Solution: Temporarily disabling the firewall is not recommended, but it can be used as an initial test to check if it is blocking connections.

1. Disable the firewall temporarily: Go to System Settings → Network → Firewall and toggle it off for a test run. Important: Turn it back on after testing.

2. If the test run succeeds and the issue is resolved, add a firewall rule to allow connections to the required binaries.

3. Identify the Fabric binaries: Ensure peer and orderer binaries are located at

   /Users/<user>/go/src/github.com/hyperledger-labs/fabric/bin/ 

4. Sign the binaries to prevent macOS from blocking them as untrusted:

   sudo codesign --force --deep --sign - /Users/<user>/go/src/github.com/hyperledger-labs/fabric/bin/orderer sudo codesign --force --deep --sign - /Users/<user>/go/src/github.com/hyperledger-labs/fabric/bin/peer 

5. Add firewall rules to allow the binaries:

   sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /Users/<user>/go/src/github.com/hyperledger-labs/fabric/bin/orderer sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /Users/<user>/go/src/github.com/hyperledger-labs/fabric/bin/orderer sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /Users/<user>/go/src/github.com/hyperledger-labs/fabric/bin/peer sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /Users/<user>/go/src/github.com/hyperledger-labs/fabric/bin/peer 

6. Reboot your machine to apply the changes.

When: Running tests using Podman

Error:

docker command not found 

Solution: One solution would be to set an alias

alias docker=podman 

However, this will require extra changes to make it work from within scripts.

A more general solution would be to create another file /usr/local/bin/docker and make sure it has execute rights and is in your $PATH:

#!/bin/sh [ -e /etc/containers/nodocker ] || \ echo "Emulate Docker CLI using podman. Create /etc/containers/nodocker to quiet msg." >&2 exec podman "$@" 

When: Running tests using Podman

Error:

Post "http://unix.sock/networks/create": dial unix /var/run/docker.sock: connect: no such file or directory 

Solution:

1. Open Podman Desktop
2. Make sure you have enabled Docker compatibility under Settings > Experimental > Docker Compatibility enabled
3. Enable Third-Party Docker Tool Compatibility under Settings > Docker compatibility

When: Running tests using Podman

Error:

bad parameter: link is not supported 

Explanation: Podman does not support the option --link (it is also deprecated in Docker.

Solution: Replace --link with --network.

When: During compilation (or test run) of integration tests

Error:

Build Error: go test -c -o ~/go/src/github.com/hyperledger-labs/fabric-token-sdk/integration/* -gcflags all=-N -l . # github.com/hyperledger/fabric/bccsp/pkcs11 ../../../../../../../../pkg/mod/github.com/hyperledger/fabric@v1.4.0-rc1.0.20230405174026-695dd57e01c2/bccsp/pkcs11/pkcs11.go:41:21: undefined: pkcs11.Ctx ../../../../../../../../pkg/mod/github.com/hyperledger/fabric@v1.4.0-rc1.0.20230405174026-695dd57e01c2/bccsp/pkcs11/pkcs11.go:51:23: undefined: pkcs11.SessionHandle ../../../../../../../../pkg/mod/github.com/hyperledger/fabric@v1.4.0-rc1.0.20230405174026-695dd57e01c2/bccsp/pkcs11/pkcs11.go:52:22: undefined: pkcs11.SessionHandle ../../../../../../../../pkg/mod/github.com/hyperledger/fabric@v1.4.0-rc1.0.20230405174026-695dd57e01c2/bccsp/pkcs11/pkcs11.go:55:32: undefined: pkcs11.ObjectHandle ../../../../../../../../pkg/mod/github.com/hyperledger/fabric@v1.4.0-rc1.0.20230405174026-695dd57e01c2/bccsp/pkcs11/pkcs11.go:326:51: undefined: pkcs11.SessionHandle ../../../../../../../../pkg/mod/github.com/hyperledger/fabric@v1.4.0-rc1.0.20230405174026-695dd57e01c2/bccsp/pkcs11/pkcs11.go:338:46: undefined: pkcs11.SessionHandle ../../../../../../../../pkg/mod/github.com/hyperledger/fabric@v1.4.0-rc1.0.20230405174026-695dd57e01c2/bccsp/pkcs11/pkcs11.go:370:50: undefined: pkcs11.SessionHandle ../../../../../../../../pkg/mod/github.com/hyperledger/fabric@v1.4.0-rc1.0.20230405174026-695dd57e01c2/bccsp/pkcs11/pkcs11.go:385:51: undefined: pkcs11.SessionHandle ../../../../../../../../pkg/mod/github.com/hyperledger/fabric@v1.4.0-rc1.0.20230405174026-695dd57e01c2/bccsp/pkcs11/pkcs11.go:684:72: undefined: pkcs11.ObjectHandle ../../../../../../../../pkg/mod/github.com/hyperledger/fabric@v1.4.0-rc1.0.20230405174026-695dd57e01c2/bccsp/pkcs11/pkcs11.go:693:77: undefined: pkcs11.ObjectHandle ../../../../../../../../pkg/mod/github.com/hyperledger/fabric@v1.4.0-rc1.0.20230405174026-695dd57e01c2/bccsp/pkcs11/pkcs11.go:693:77: too many errors (exit status 1) 

Explanation: GCO option is not enabled.

Solution: Enable GCO via go env -w CGO_ENABLED=1.