{
  "id": "flutter/networkerror-dns-lookup-failed",
  "signature": "NetworkError: DNS lookup failed for host 'example.com'",
  "signature_zh": "NetworkError：主机 'example.com' 的 DNS 查找失败",
  "regex": "NetworkError: DNS lookup failed for host '.*'",
  "domain": "flutter",
  "category": "network_error",
  "subcategory": null,
  "root_cause": "The device could not resolve the hostname to an IP address due to network connectivity issues, incorrect DNS configuration, or the host being unreachable.",
  "root_cause_type": "generic",
  "root_cause_zh": "设备无法将主机名解析为 IP 地址，原因是网络连接问题、DNS 配置错误或主机不可达。",
  "versions": [
    {
      "version": "Flutter 2.10",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Flutter 3.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Flutter 3.7",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Hardcoding IP addresses instead of hostnames",
      "why_fails": "IP addresses can change; not a scalable solution and may break on different networks.",
      "fail_rate": 0.5,
      "condition": "",
      "sources": []
    },
    {
      "action": "Disabling DNS resolution and using raw IP in the app code",
      "why_fails": "Same as above; also violates best practices and may cause security warnings.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    },
    {
      "action": "Assuming the error is always on the server side",
      "why_fails": "Often the client's DNS configuration or network is the issue; server may be fine.",
      "fail_rate": 0.4,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Check the device's network connectivity and retry with exponential backoff:\nimport 'dart:io';\n\nFuture<bool> checkConnectivity() async {\n  try {\n    final result = await InternetAddress.lookup('example.com');\n    return result.isNotEmpty && result[0].rawAddress.isNotEmpty;\n  } on SocketException catch (_) {\n    return false;\n  }\n}",
      "success_rate": 0.85,
      "how": "Check the device's network connectivity and retry with exponential backoff:\nimport 'dart:io';\n\nFuture<bool> checkConnectivity() async {\n  try {\n    final result = await InternetAddress.lookup('example.com');\n    return result.isNotEmpty && result[0].rawAddress.isNotEmpty;\n  } on SocketException catch (_) {\n    return false;\n  }\n}",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use a custom DNS resolver or fallback to a different DNS server, e.g., Google's 8.8.8.8, by configuring the HttpClient:\nHttpClient client = HttpClient();\nclient.findProxy = (uri) {\n  return 'PROXY 8.8.8.8:53; DIRECT';\n};",
      "success_rate": 0.75,
      "how": "Use a custom DNS resolver or fallback to a different DNS server, e.g., Google's 8.8.8.8, by configuring the HttpClient:\nHttpClient client = HttpClient();\nclient.findProxy = (uri) {\n  return 'PROXY 8.8.8.8:53; DIRECT';\n};",
      "condition": "",
      "sources": []
    },
    {
      "action": "Implement a retry mechanism with a timeout and user-friendly error message:\ntry {\n  await http.get(Uri.parse('https://example.com')).timeout(Duration(seconds: 10));\n} on SocketException {\n  // show error to user\n}",
      "success_rate": 0.8,
      "how": "Implement a retry mechanism with a timeout and user-friendly error message:\ntry {\n  await http.get(Uri.parse('https://example.com')).timeout(Duration(seconds: 10));\n} on SocketException {\n  // show error to user\n}",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Check the device's network connectivity and retry with exponential backoff:\nimport 'dart:io';\n\nFuture<bool> checkConnectivity() async {\n  try {\n    final result = await InternetAddress.lookup('example.com');\n    return result.isNotEmpty && result[0].rawAddress.isNotEmpty;\n  } on SocketException catch (_) {\n    return false;\n  }\n}",
    "Use a custom DNS resolver or fallback to a different DNS server, e.g., Google's 8.8.8.8, by configuring the HttpClient:\nHttpClient client = HttpClient();\nclient.findProxy = (uri) {\n  return 'PROXY 8.8.8.8:53; DIRECT';\n};",
    "Implement a retry mechanism with a timeout and user-friendly error message:\ntry {\n  await http.get(Uri.parse('https://example.com')).timeout(Duration(seconds: 10));\n} on SocketException {\n  // show error to user\n}"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://api.flutter.dev/flutter/dart-io/HttpClient-class.html",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.81,
  "fix_success_rate": 0.8,
  "resolvable": "partial",
  "first_seen": "2023-03-25",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}