ArcGIS Layer Troubleshooting

Overview

This guide explains how to troubleshoot ArcGIS layers that load slowly, return incomplete data, or fail to render in Maptaskr Power Maps.

It is written for admins, GIS teams, and infrastructure teams working with ArcGIS Enterprise or ArcGIS Online services.

Typical Symptoms

• Layer appears in configuration but does not render consistently.
• Requests to /query or /export return 504 Gateway Timeout.
• Binary payloads (PBF/PNG) are returned as text or mutated content.
• Layer metadata reports capabilities that do not work in practice (for example PBF or quantization support).
• Layer only responds for very small extents, then times out as extent increases.

Why This Happens More Often In Power Maps

Maptaskr Power Maps follows ArcGIS metadata and capabilities more strictly than Maptaskr Classic (v2):

• Power Maps reads service and layer metadata first.
• Power Maps chooses request format and projection from actual capabilities/config.
• Power Maps uses tile-based querying and request cancellation for map movement.
• Power Maps can use PBF and quantization where supported.

Classic (v2) generally forced Web Mercator-style behavior and ignored several metadata details. This could appear to work in environments where strict capability handling reveals server or proxy limitations.

Layer Load Lifecycle (What Power Maps Does)

1. Service discovery

Power Maps queries the service root endpoint:

https://<host>/ArcGIS/rest/services/<service-name>/<FeatureServer|MapServer>?f=json

From this response it reads:

• Service metadata (name, description)
• Available sublayers (layers)

2. Sublayer discovery

After a sublayer is selected, Power Maps queries:

https://<host>/ArcGIS/rest/services/<service-name>/<FeatureServer|MapServer>/<layer-id>?f=json

From this response it reads:

• supportedQueryFormats (for example JSON, PBF)
• tileMaxRecordCount
• spatialReference or sourceSpatialReference
• supportsCoordinatesQuantization
• fields
• drawingInfo

Depending on config, Power Maps may also test:

• MOD operator support
• 4326 extent retrieval when native projection is not 4326
• /legend endpoint (MapServer)

3. Tile query execution

Power Maps uses tile extents and sends /query calls per tile.

Common query shape:

f=<pbf|json>
outFields=*
resultType=tile
where=1=1
resultRecordCount=<tileMaxRecordCount>
resultOffset=0
outSR=<4326|native>
inSR=<layer-sr>
returnGeometry=true
geometry=<tile-extent>
geometryType=esriGeometryEnvelope
spatialRel=esriSpatialRelIntersects
quantizationParameters=<if enabled and supported>

MapServer behavior:

• Requests /export for image tile rendering.
• Requests /query for feature interaction details.

FeatureServer behavior:

• Uses /query only.

Most Common Root Causes

1. Proxy or firewall mutates binary responses

If a reverse proxy or firewall converts binary payloads to text, base64, or altered content types, the browser cannot decode PBF/PNG correctly.

Expected:

• PBF stays binary protobuf.
• PNG stays binary image.
• Correct MIME types and no body mutation.

2. Metadata advertises unsupported capabilities

Some services report support for:

• PBF
• Quantization
• Specific projections

But fail when those options are actually used.

3. Projection or extent processing is too expensive

Requests in either 4326 or native SR may time out under load, especially for large extents or complex geometries.

4. Slow baseline query performance

If minimal checks are slow (for example ID-only query with where=1=1), the issue is usually server-side performance, datastore/indexing, or infrastructure path latency.

Diagnostic Workflow

Use browser DevTools Network tab and verify each step:

1. Confirm service root (?f=json) returns quickly.
2. Confirm sublayer spec (/<layer-id>?f=json) returns expected capabilities.
3. Compare a minimal query:

.../query?f=json&where=1%3D1&returnIdsOnly=true&resultRecordCount=1

4. Compare format behavior:

• JSON query
• PBF query
• MapServer /export PNG

5. Validate content handling:

• HTTP status is 200
• Content-Type matches payload
• Response body is not transformed by intermediary devices

6. Compare projections:

• Native SR query
• EPSG:4326 query

7. Test small extent vs large extent to isolate scaling issues.

Recommended Remediation

GIS Team

• Validate that advertised capabilities actually work (supportedQueryFormats, quantization, SR handling).
• Ensure spatial indexes and attribute indexes are healthy for common filters.
• Test heavy layers independently with tile-style extent queries.
• Reduce geometry complexity where possible.

Infrastructure / Network Team

• Disable payload mutation for ArcGIS endpoints.
• Preserve binary payloads end-to-end (PBF/PNG).
• Preserve upstream Content-Type headers.
• Increase timeout limits if backend is known to be slow while optimization is in progress.
• Confirm no WAF rules are rewriting or scanning binary ArcGIS responses in a way that alters output.

Power Maps Configuration Workarounds

Use these as temporary controls while root cause is fixed:

• Force JSON instead of PBF for affected layers.
• Disable quantization for layers that fail with quantization parameters.
• Use native projection with client-side reprojection only where appropriate.
• Lower resultRecordCount / tile feature limits.
• Apply attribute filters to reduce per-tile volume.

Quick Decision Matrix

Test Result	Likely Cause	Next Action
JSON works, PBF fails	Binary handling issue	Inspect proxy/firewall response mutation
Small extent works, large extent times out	Backend performance bottleneck	Tune indexes, geometry complexity, timeout
Metadata says supported, request fails	Capability mismatch	Override config, fix service metadata/config
Both 4326 and native SR fail	General service latency/load	Profile service and infrastructure path

Escalation Package Checklist

When escalating to GIS/IT teams, provide:

• Service URL and layer ID
• Timestamp and timezone of failures
• Full request URL (or sanitized query params)
• Response status and headers
• Whether JSON/PBF/PNG each worked or failed
• Whether issue is extent-size dependent
• Projection used (inSR/outSR)
• Screenshot of Network payload and response details

Practical Baseline

If one reference layer responds quickly in native SR while another layer times out, prioritize:

• Comparing service configuration and indexes between the two layers
• Comparing geometry complexity and feature density
• Checking if only the failing layer crosses a stricter proxy/firewall path

This usually separates product configuration issues from backend service limitations.