HyperRoute

Troubleshooting

Common Issues

"Router not responding"

⚠️  Cannot connect to router at http://localhost:4000

The router is not running. Start it first:

routerd --bundle .hyperroute

REST subgraph returns 404

Ensure:

  1. Your schema has @rest directives on Query/Mutation fields
  2. You pushed with --subgraph-type rest
  3. The --url is the base URL (e.g., http://localhost:4001, not http://localhost:4001/graphql)
  4. The path in @rest matches your API routes (e.g., /users/{args.id})

gRPC "h2 protocol error"

This typically means a TLS mismatch. If your gRPC service runs in plaintext mode (no TLS), do not pass --grpc-tls.

gRPC "service not found"

Ensure the --grpc-service flag and the service argument in @grpc directives match the exact service name from your .proto file:

# Correct
inventory.v1.ProductService

# Wrong
inventory.v1.InventoryService

"subgraph_type: rest not recognized"

Ensure you're running DevKit v0.3.8+. The rest subgraph type was added in this version.

hyperroute version

Diagnostic Commands

# Full environment check
hyperroute doctor

# Check compatibility between DevKit, routerd, and bundle
hyperroute compat

# Validate a bundle
hyperroute validate --path .hyperroute

# Inspect bundle contents
cat .hyperroute/subgraphs.json
cat .hyperroute/supergraph.graphql | grep "@rest\|@grpc"

Getting Help

  • Run hyperroute doctor for a comprehensive diagnostic report
  • Use --verbose on any command for detailed debug output
  • Use --format json for machine-parseable error details
  • Contact support@hyperroute.dev for assistance