---
title: Troubleshooting
description: Common Marteso setup and workflow issues and how to fix them.
---

# Troubleshooting

## App connection issues

### My app doesn't appear in the search results

**Cause:** The app name or bundle ID search didn't match the App Store listing.

**Fix:**
- Search by exact App Store title rather than internal name
- Try searching by bundle ID directly (e.g. `com.yourcompany.yourapp`)
- If the app was very recently submitted or approved, wait 24 hours for the App Store index to update before trying again
- Check that you're connecting to the correct region — some apps are only available in specific storefronts

---

### Marteso shows metadata from the wrong app

**Cause:** Two apps have similar names and the wrong one was selected during setup.

**Fix:**
1. Go to **Apps → [app name] → Settings → Remove app**
2. Re-add the app using the exact bundle ID instead of the name search

---

## Keyword sync timing

### New keywords show no rank after 24 hours

**Cause:** The ranking scan hasn't completed for this keyword, or the app isn't in the top 250.

**Fix:**
- Wait up to 48 hours for new keywords, especially for less common storefronts
- A blank rank means your app isn't currently in the top 250 for that term — this is normal for competitive keywords
- If ranks still don't appear after 48 hours, check that the keyword contains only standard characters (some Unicode terms cause scan failures)

---

### Rankings stopped updating

**Cause:** A scraping issue, App Store API change, or platform problem interrupted the daily ranking scan.

**Fix:**
- Check status.marteso.com for any known incidents
- If rankings for all keywords in all countries stopped on the same day, it's likely a platform issue — wait for it to resolve
- If only one country's rankings stopped, try removing and re-adding keywords for that country
- Contact support if rankings haven't updated for more than 48 hours

---

### Rank shows a number that seems wrong

**Cause:** App Store ranks fluctuate throughout the day. Marteso captures a daily snapshot, but the rank when you check the App Store manually may differ.

**Fix:**
- Compare ranks at the same time each day for consistency
- Expect ±5 position variance on high-competition keywords — this is normal
- Large unexplained rank swings (20+ positions) often correlate with App Store algorithm updates; check if the same date shows rank movements for your competitors

---

## Missing rank movement after a metadata update

### I updated metadata 2 weeks ago but ranks haven't changed

**Cause:** App Store metadata changes take 1–4 weeks to reflect in ranking signals. Some competitive keywords take longer.

**Fix:**
- Give the update a full 4 weeks before drawing conclusions
- Check whether your App Store version submission was approved (pending review holds can delay metadata going live)
- Look at less competitive terms first — long-tail keywords move faster than high-difficulty category terms

---

### Rank improved but downloads didn't

**Cause:** Better ranks on terms that don't match conversion intent.

**Fix:**
- Check the search intent behind the keywords that improved — are these terms users actually download from?
- Look at your impressions and page view data in Analytics — if views increased but downloads didn't, the product page (screenshots, icon, first lines of description) may be the conversion bottleneck
- Review the [Screenshot automation](../guides/screenshot-automation.md) and [AI metadata](../guides/ai-metadata.md) guides for conversion optimization

---

## AI metadata suggestions

### No suggestions are appearing for my app

**Cause:** Suggestions are generated on a schedule and require enough tracked keyword data to produce meaningful results.

**Fix:**
- Ensure your app has at least 20 tracked keywords with ranking data
- Wait 24–48 hours after the first sync for the suggestion engine to run
- Check that your app has a primary country set under **Apps → [app name] → Settings**

---

### Suggestion confidence scores are all below 0.6

**Cause:** Insufficient rank data, or the app's current keyword list doesn't have enough signal for the AI to build confident suggestions.

**Fix:**
- Add more keywords and wait for ranking data to accumulate
- Confidence scores typically improve after 2–4 weeks of rank history
- Scores below 0.6 are experimental ideas, not recommendations — use them as starting points to edit from

---

## Support escalation

If none of the above resolves your issue:

1. **Check** status.marteso.com for active incidents
2. **Search** the in-product Help (? icon in the sidebar) for your specific error message
3. **Email** support@marteso.com with:
   - Your workspace ID (found in **Settings → Workspace**)
   - The app bundle ID affected
   - A description of the issue and when it started
   - Any error messages or screenshots

Support response time is within 1 business day for Pro and Agency plans, within 3 business days for Starter.