ErrorFormatter

class ErrorFormatter

Formats exceptions into user-friendly error messages.

This class provides static methods to convert technical exceptions into clear, actionable error messages that help users understand what went wrong and how to fix it.

Constructors

ErrorFormatter()

ErrorFormatter()

Properties

hashCode no setter inherited

int get hashCode

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Inherited from Object.

Implementation

dart

external int get hashCode;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

dart

external Type get runtimeType;

Methods

noSuchMethod() inherited

dynamic noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dart

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

dart

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

Implementation

dart

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

toString() inherited

String toString()

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.

Inherited from Object.

Implementation

dart

external String toString();

Operators

operator ==() inherited

bool operator ==(Object other)

The equality operator.

The default behavior for all Objects is to return true if and only if this object and other are the same object.

Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:

Total: It must return a boolean for all arguments. It should never throw.
Reflexive: For all objects o, o == o must be true.
Symmetric: For all objects o1 and o2, o1 == o2 and o2 == o1 must either both be true, or both be false.
Transitive: For all objects o1, o2, and o3, if o1 == o2 and o2 == o3 are true, then o1 == o3 must be true.

The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.

If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.

Inherited from Object.

Implementation

dart

external bool operator ==(Object other);

Static Methods

format()

String format(dynamic error)

Formats any exception into a user-friendly message.

This is the main entry point that delegates to specific formatters based on exception type. Falls back to generic message if no specific formatter matches.

Example:

dart

try {
  await downloadFile(url);
} catch (e) {
  print(ErrorFormatter.format(e));
}

Implementation

dart

static String format(dynamic error) {
  if (error == null) {
    return 'Unknown error occurred';
  }

  final errorString = error.toString();

  &#47;&#47; Network errors
  if (error is SocketException || errorString.contains('SocketException')) {
    return formatNetworkError(error);
  }
  if (error is HttpException ||
      errorString.contains('HttpException') ||
      errorString.contains('HTTP 404') ||
      errorString.contains('HTTP 403') ||
      errorString.contains('HTTP 5')) {
    return formatHttpError(error);
  }
  if (error is TimeoutException || errorString.contains('TimeoutException')) {
    return formatTimeoutError(error);
  }

  &#47;&#47; Platform errors
  if (error is UnsupportedError || errorString.contains('Unsupported')) {
    return formatPlatformError(error);
  }

  &#47;&#47; Permission errors
  if (errorString.contains('Permission denied') ||
      errorString.contains('Access denied')) {
    return formatPermissionError(error);
  }

  &#47;&#47; Checksum errors
  if (errorString.contains('ChecksumValidationException') ||
      errorString.contains('checksum')) {
    return formatChecksumError(error);
  }

  &#47;&#47; GitHub API errors
  if (errorString.contains('GitHubReleaseException')) {
    return formatGitHubError(error);
  }

  &#47;&#47; Archive extraction errors
  if (errorString.contains('Archive') || errorString.contains('extract')) {
    return formatArchiveError(error);
  }

  &#47;&#47; Process errors
  if (errorString.contains('ProcessException')) {
    return formatProcessError(error);
  }

  &#47;&#47; Cache errors
  if (errorString.contains('CacheException')) {
    return formatCacheError(error);
  }

  &#47;&#47; Retry exhausted
  if (errorString.contains('RetryExhaustedException')) {
    return formatRetryExhaustedError(error);
  }

  &#47;&#47; Generic fallback
  return formatGenericError(error);
}

formatArchiveError()

String formatArchiveError(dynamic error)

Formats archive extraction errors.

Implementation

dart

static String formatArchiveError(dynamic error) {
  return '''
Failed to extract archive.

The downloaded archive could not be extracted.

Possible causes:
• Corrupted download
• Unsupported archive format
• Disk space full
• Permission issues

Try:
• Clear cache and download again
• Check available disk space
• Verify you have write permissions

Technical details: $error
''';
}

formatCacheError()

String formatCacheError(dynamic error)

Formats cache-related errors.

Implementation

dart

static String formatCacheError(dynamic error) {
  return '''
Cache operation failed.

An error occurred while accessing the cache directory.

Common causes:
• Insufficient disk space
• Permission issues
• Corrupted cache files

Try:
• Check available disk space
• Verify write permissions
• Clear cache manually and try again:
  macOS&#47;Linux: rm -rf ~&#47;.cache&#47;network_debugger&#47;
  Windows: del &#47;s &#47;q %LOCALAPPDATA%\\network_debugger\\Cache\\

Technical details: $error
''';
}

formatChecksumError()

String formatChecksumError(dynamic error)

Formats checksum validation errors.

Implementation

dart

static String formatChecksumError(dynamic error) {
  return '''
Security validation failed: Checksum mismatch.

The downloaded file's checksum doesn't match the expected value.
This could indicate:
• File corruption during download
• Security issue (file was tampered with)
• Network transmission error

For security reasons, the file will not be used.

What to do:
1. Clear the cache: network_debugger --clear-cache (if implemented)
2. Try downloading again
3. If problem persists, report at:
   https:&#47;&#47;github.com&#47;cherrypick-agency&#47;flutter_network_debugger&#47;issues

To skip validation (NOT RECOMMENDED):
• Use skipChecksumValidation parameter (API only)

Technical details: $error
''';
}

formatGenericError()

String formatGenericError(dynamic error)

Formats generic/unknown errors.

Implementation

dart

static String formatGenericError(dynamic error) {
  return '''
An unexpected error occurred.

Error: $error

If this problem persists, please report it at:
https:&#47;&#47;github.com&#47;cherrypick-agency&#47;flutter_network_debugger&#47;issues

Include:
• Your operating system and version
• Command you ran
• Full error message above
• Whether --verbose flag shows more details
''';
}

formatGitHubError()

String formatGitHubError(dynamic error)

Formats GitHub API errors.

Implementation

dart

static String formatGitHubError(dynamic error) {
  return '''
GitHub API error.

Failed to fetch release information from GitHub.

Common causes:
• Release not found
• API rate limiting
• Repository moved or renamed
• Temporary GitHub outage

Try:
• Check your internet connection
• Verify the release exists
• Wait if rate limited (resets hourly)
• Check GitHub status: githubstatus.com

Technical details: $error
''';
}

formatHttpError()

String formatHttpError(dynamic error)

Formats HTTP errors (non-200 status codes).

Implementation

dart

static String formatHttpError(dynamic error) {
  final errorString = error.toString();

  if (errorString.contains('404') || errorString.contains('Not Found')) {
    return '''
Resource not found (HTTP 404).

This usually means:
• The binary for your platform is not available in this release
• The release version you specified doesn't exist
• The GitHub repository structure has changed

Try:
• Omit the --binary-version flag to use the latest version
• Check available releases at: github.com&#47;cherrypick-agency&#47;flutter_network_debugger&#47;releases

Technical details: $error
''';
  }

  if (errorString.contains('403') || errorString.contains('Forbidden')) {
    return '''
Access forbidden (HTTP 403).

This might be caused by:
• GitHub API rate limiting (60 requests&#47;hour for unauthenticated users)
• Geographic restrictions
• Repository access permissions

Try:
• Wait an hour and try again
• Set GITHUB_TOKEN environment variable to increase rate limit

Technical details: $error
''';
  }

  if (errorString.contains('500') ||
      errorString.contains('502') ||
      errorString.contains('503') ||
      errorString.contains('504')) {
    return '''
Server error (HTTP 5xx).

The remote server is experiencing issues. This is temporary.

Try:
• Wait a few minutes and try again
• Check GitHub status at: githubstatus.com

Technical details: $error
''';
  }

  return '''
HTTP error occurred while downloading.

Technical details: $error
''';
}

formatNetworkError()

String formatNetworkError(dynamic error)

Formats network connection errors.

Implementation

dart

static String formatNetworkError(dynamic error) {
  return '''
Network connection error: Unable to connect to the internet.

Possible solutions:
• Check your internet connection
• Verify firewall settings aren't blocking the connection
• Try again in a few moments
• If behind a proxy, ensure proxy settings are configured

Technical details: $error
''';
}

formatPermissionError()

String formatPermissionError(dynamic error)

Formats permission/access denied errors.

Implementation

dart

static String formatPermissionError(dynamic error) {
  return '''
Permission denied.

The application doesn't have sufficient permissions to perform this operation.

Common causes:
• Cannot write to cache directory
• Cannot execute the downloaded binary
• Directory&#47;file is read-only

Try:
• Check permissions on cache directory
• On Unix systems: chmod +x on the binary if needed
• Run with appropriate privileges
• Check antivirus&#47;security software isn't blocking execution

Cache location varies by platform:
• macOS&#47;Linux: ~&#47;.cache&#47;network_debugger&#47;
• Windows: %LOCALAPPDATA%\\network_debugger\\Cache\\

Technical details: $error
''';
}

formatPlatformError()

String formatPlatformError(dynamic error)

Formats platform/architecture errors.

Implementation

dart

static String formatPlatformError(dynamic error) {
  final errorString = error.toString();

  return '''
Platform not supported.

Your platform&#47;architecture is not currently supported.

Current platform: $errorString

Supported platforms:
• macOS (Intel&#47;ARM)
• Linux (amd64&#47;arm64)
• Windows (32-bit&#47;64-bit&#47;ARM)

If you believe this is an error, please report it at:
https:&#47;&#47;github.com&#47;cherrypick-agency&#47;flutter_network_debugger&#47;issues

Technical details: $error
''';
}

formatProcessError()

String formatProcessError(dynamic error)

Formats process execution errors.

Implementation

dart

static String formatProcessError(dynamic error) {
  final errorString = error.toString();

  if (errorString.contains('port') || errorString.contains('ADDR')) {
    return '''
Failed to start debugger: Port already in use.

The specified port is already occupied by another process.

Try:
• Use a different port: network_debugger --port 8080
• Find and stop the process using the port
• On Unix: lsof -i :9092
• On Windows: netstat -ano | findstr :9092

Technical details: $error
''';
  }

  if (errorString.contains('not found') || errorString.contains('binary')) {
    return '''
Failed to start debugger: Binary not found or not executable.

The debugger binary could not be started.

Try:
• Clear cache and download again
• On Unix systems: ensure binary has execute permissions
• Check antivirus isn't blocking the file

Technical details: $error
''';
  }

  return '''
Failed to start debugger process.

The debugger process could not be started.

Try:
• Clear cache: rm -rf ~&#47;.cache&#47;network_debugger&#47; (macOS&#47;Linux)
• Download the binary again
• Check system resources (RAM, disk space)
• Review security software settings

Technical details: $error
''';
}

formatRetryExhaustedError()

String formatRetryExhaustedError(dynamic error)

Formats retry exhausted errors.

Implementation

dart

static String formatRetryExhaustedError(dynamic error) {
  return '''
Operation failed after multiple retry attempts.

The operation was retried several times but continued to fail.

This suggests a persistent problem:
• Network connectivity issues
• Server is down
• Resource unavailable

Try:
• Check your internet connection
• Verify the resource exists
• Try again later
• Check service status

Technical details: $error
''';
}

formatShort()

String formatShort(dynamic error)

Extracts a short, one-line error message.

Useful for logging or displaying errors inline.

Implementation

dart

static String formatShort(dynamic error) {
  if (error == null) return 'Unknown error';

  final errorString = error.toString();

  if (error is SocketException || errorString.contains('SocketException')) {
    return 'Network connection error';
  }
  if (error is TimeoutException) {
    return 'Operation timed out';
  }
  if (errorString.contains('404')) {
    return 'Resource not found (HTTP 404)';
  }
  if (errorString.contains('403')) {
    return 'Access forbidden - possible rate limit (HTTP 403)';
  }
  if (errorString.contains('ChecksumValidationException')) {
    return 'Checksum validation failed - file may be corrupted';
  }
  if (errorString.contains('Permission denied')) {
    return 'Permission denied';
  }
  if (errorString.contains('UnsupportedError')) {
    return 'Platform not supported';
  }

  &#47;&#47; Truncate long messages
  if (errorString.length > 100) {
    return '${errorString.substring(0, 97)}...';
  }

  return errorString;
}

formatTimeoutError()

String formatTimeoutError(dynamic error)

Formats timeout errors.

Implementation

dart

static String formatTimeoutError(dynamic error) {
  return '''
Operation timed out.

The operation took too long to complete. This can happen with:
• Slow internet connection
• Large file downloads
• Server not responding

Try:
• Check your internet speed
• Try again when you have a better connection
• If the problem persists, the server might be down

Technical details: $error
''';
}

ErrorFormatter ​

Constructors ​

ErrorFormatter() ​

Properties ​

hashCode no setter inherited ​

runtimeType no setter inherited ​

Methods ​

noSuchMethod() inherited ​

toString() inherited ​

Operators ​

operator ==() inherited ​

Static Methods ​

format() ​

formatArchiveError() ​

formatCacheError() ​

formatChecksumError() ​

formatGenericError() ​

formatGitHubError() ​

formatHttpError() ​

formatNetworkError() ​

formatPermissionError() ​

formatPlatformError() ​

formatProcessError() ​

formatRetryExhaustedError() ​

formatShort() ​

formatTimeoutError() ​

ErrorFormatter

Constructors

ErrorFormatter()

Properties

hashCode no setter inherited

runtimeType no setter inherited

Methods

noSuchMethod() inherited

toString() inherited

Operators

operator ==() inherited

Static Methods

format()

formatArchiveError()

formatCacheError()

formatChecksumError()

formatGenericError()

formatGitHubError()

formatHttpError()

formatNetworkError()

formatPermissionError()

formatPlatformError()

formatProcessError()

formatRetryExhaustedError()

formatShort()

formatTimeoutError()