fix: improve error message when starting server (#3008)

When transports fail to listen, include specific error messages and
advice on how to proceed.

Author: achingbrain

packages/integration-tests/test/listening.spec.ts

@@ -53,7 +53,7 @@ describe('Listening', () => {
     })
 
     await expect(libp2p.start()).to.eventually.be.rejected
-      .with.property('name', 'NoValidAddressesError')
+      .with.property('name', 'UnsupportedListenAddressesError')
   })
 
   it('does not fail to start if provided listen multiaddr are not compatible to configured transports (when supporting dial only mode)', async () => {

packages/libp2p/src/errors.ts

@@ -59,6 +59,20 @@ export class DialDeniedError extends Error {
   }
 }
 
+export class UnsupportedListenAddressError extends Error {
+  constructor (message = 'No transport was configured to listen on this address') {
+    super(message)
+    this.name = 'UnsupportedListenAddressError'
+  }
+}
+
+export class UnsupportedListenAddressesError extends Error {
+  constructor (message = 'Configured listen addresses could not be listened on') {
+    super(message)
+    this.name = 'UnsupportedListenAddressesError'
+  }
+}
+
 export class NoValidAddressesError extends Error {
   constructor (message = 'No valid addresses') {
     super(message)

packages/libp2p/src/transport-manager.ts

@@ -2,7 +2,7 @@ import { FaultTolerance, InvalidParametersError, NotStartedError } from '@libp2p
 import { trackedMap } from '@libp2p/utils/tracked-map'
 import { IP4, IP6 } from '@multiformats/multiaddr-matcher'
 import { CustomProgressEvent } from 'progress-events'
-import { NoValidAddressesError, TransportUnavailableError } from './errors.js'
+import { TransportUnavailableError, UnsupportedListenAddressError, UnsupportedListenAddressesError } from './errors.js'
 import type { Libp2pEvents, ComponentLogger, Logger, Connection, TypedEventTarget, Metrics, Startable, Listener, Transport, Upgrader } from '@libp2p/interface'
 import type { AddressManager, TransportManager, TransportManagerDialOptions } from '@libp2p/interface-internal'
 import type { Multiaddr } from '@multiformats/multiaddr'
@@ -25,7 +25,7 @@ interface IPStats {
 }
 
 interface ListenStats {
-  unsupportedAddresses: Set<string>
+  errors: Map<string, Error>
   ipv4: IPStats
   ipv6: IPStats
 }
@@ -207,9 +207,7 @@ export class DefaultTransportManager implements TransportManager, Startable {
     // track IPv4/IPv6 results - if we succeed on IPv4 but all IPv6 attempts
     // fail then we are probably on a network without IPv6 support
     const listenStats: ListenStats = {
-      unsupportedAddresses: new Set(
-        addrs.map(ma => ma.toString())
-      ),
+      errors: new Map(),
       ipv4: {
         success: 0,
         attempts: 0
@@ -220,6 +218,10 @@ export class DefaultTransportManager implements TransportManager, Startable {
       }
     }
 
+    addrs.forEach(ma => {
+      listenStats.errors.set(ma.toString(), new UnsupportedListenAddressError())
+    })
+
     const tasks: Array<Promise<void>> = []
 
     for (const [key, transport] of this.transports.entries()) {
@@ -269,7 +271,7 @@ export class DefaultTransportManager implements TransportManager, Startable {
         tasks.push(
           listener.listen(addr)
             .then(() => {
-              listenStats.unsupportedAddresses.delete(addr.toString())
+              listenStats.errors.delete(addr.toString())
 
               if (IP4.matches(addr)) {
                 listenStats.ipv4.success++
@@ -280,6 +282,7 @@ export class DefaultTransportManager implements TransportManager, Startable {
               }
             }, (err) => {
               this.log.error('transport %s could not listen on address %a - %e', key, addr, err)
+              listenStats.errors.set(addr.toString(), err)
               throw err
             })
         )
@@ -308,9 +311,13 @@ export class DefaultTransportManager implements TransportManager, Startable {
     }
 
     // if a configured address was not able to be listened on, throw an error
-    throw new NoValidAddressesError(`No configured transport could listen on these addresses, please remove them from your config: ${[
-      ...listenStats.unsupportedAddresses
-    ].join(', ')}`)
+    throw new UnsupportedListenAddressesError(`Some configured addresses failed to be listened on, you may need to remove one or more listen addresses from your configuration or set \`transportManager.faultTolerance\` to NO_FATAL:\n${
+      [...listenStats.errors.entries()].map(([addr, err]) => {
+        return `
+  ${addr}: ${`${err.stack ?? err}`.split('\n').join('\n  ')}
+`
+      }).join('')
+    }`)
   }
 
   private ipv6Unsupported (listenStats: ListenStats): boolean {

packages/libp2p/test/transports/transport-manager.spec.ts

@@ -123,7 +123,7 @@ describe('Transport Manager', () => {
 
     await expect(start(tm))
       .to.eventually.be.rejected()
-      .and.to.have.property('name', 'NoValidAddressesError')
+      .and.to.have.property('name', 'UnsupportedListenAddressesError')
 
     await stop(tm)
   })
@@ -167,7 +167,7 @@ describe('Transport Manager', () => {
     transportManager.add(transport)
 
     await expect(start(transportManager)).to.eventually.be.rejected
-      .with.property('name', 'NoValidAddressesError')
+      .with.property('name', 'UnsupportedListenAddressesError')
   })
 
   it('should detect lack of IPv6 support', async () => {