fix: tighten Instagram URL detection and propagate Actor statusMessage

Author: daveomri

src/strands_apify/social_media.py

@@ -44,6 +44,20 @@
 VALID_LINKEDIN_SCRAPER_MODES = ("Short", "Full")
 
 
+def _looks_like_instagram_url(value: str) -> bool:
+    """Return True if ``value`` is a well-formed http(s) URL whose host is instagram.com.
+
+    Used by ``apify_instagram_scraper`` to decide whether a ``search_query`` should
+    be treated as a direct URL or as a plain search term. Stricter than a substring
+    check — e.g. it rejects ``"why-instagram.com-matters"`` and ``"http"``.
+    """
+    parsed = urlparse(value)
+    if parsed.scheme not in ("http", "https"):
+        return False
+    host = (parsed.hostname or "").lower()
+    return host == "instagram.com" or host.endswith(".instagram.com")
+
+
 def _extract_linkedin_username(profile_url: str) -> str:
     """Extract a LinkedIn username from a profile URL, or return the value as-is if already a username."""
     parsed = urlparse(profile_url)
@@ -136,7 +150,7 @@ def apify_instagram_scraper(
 
         if urls:
             run_input["directUrls"] = urls
-        elif search_query and ("instagram.com" in search_query or search_query.startswith("http")):
+        elif search_query and _looks_like_instagram_url(search_query):
             run_input["directUrls"] = [search_query]
         else:
             run_input["search"] = search_query

src/strands_apify/utils.py

@@ -106,11 +106,21 @@ def _success_result(text: str, panel_body: str, panel_title: str) -> dict[str, A
 
 
 def _check_run_status(actor_run: dict[str, Any], label: str) -> None:
-    """Raise RuntimeError if the Actor run did not succeed."""
+    """Raise RuntimeError if the Actor run did not succeed.
+
+    Includes the Apify-provided ``statusMessage`` in the error when present so
+    callers can see why a run failed without having to look up the run in the
+    Apify Console.
+    """
     status = actor_run.get("status", "UNKNOWN")
-    if status != "SUCCEEDED":
-        run_id = actor_run.get("id", "N/A")
-        raise RuntimeError(f"{label} finished with status {status}. Run ID: {run_id}")
+    if status == "SUCCEEDED":
+        return
+    run_id = actor_run.get("id", "N/A")
+    status_msg = actor_run.get("statusMessage")
+    parts = [f"{label} finished with status {status}", f"Run ID: {run_id}"]
+    if status_msg:
+        parts.append(f"Message: {status_msg}")
+    raise RuntimeError(". ".join(parts))
 
 
 def _validate_url(url: str) -> None:

tests/test_core.py

@@ -171,14 +171,33 @@ def test_run_actor_with_memory(mock_apify_env, mock_apify_client):
 
 
 def test_run_actor_failure(mock_apify_env, mock_apify_client):
-    """Actor run returns error dict when Actor fails."""
+    """Actor run returns error dict when Actor fails and surfaces Apify's statusMessage."""
     mock_apify_client.actor.return_value.call.return_value = MOCK_FAILED_RUN
 
     with patch("strands_apify.utils.ApifyClient", return_value=mock_apify_client):
         result = apify_run_actor(actor_id="actor/my-scraper")
 
     assert result["status"] == "error"
-    assert "FAILED" in result["content"][0]["text"]
+    text = result["content"][0]["text"]
+    assert "FAILED" in text
+    # statusMessage from MOCK_FAILED_RUN must be propagated to the user-facing error
+    assert "Actor failed with an error" in text
+
+
+def test_run_actor_failure_without_status_message(mock_apify_env, mock_apify_client):
+    """Failure error message still works when the Apify run omits statusMessage."""
+    run_without_message = {**MOCK_FAILED_RUN}
+    run_without_message.pop("statusMessage", None)
+    mock_apify_client.actor.return_value.call.return_value = run_without_message
+
+    with patch("strands_apify.utils.ApifyClient", return_value=mock_apify_client):
+        result = apify_run_actor(actor_id="actor/my-scraper")
+
+    assert result["status"] == "error"
+    text = result["content"][0]["text"]
+    assert "FAILED" in text
+    assert "Run ID" in text
+    assert "Message:" not in text
 
 
 def test_run_actor_timeout(mock_apify_env, mock_apify_client):

tests/test_social_media.py

@@ -6,6 +6,7 @@
 
 from strands_apify.social_media import (
     _extract_linkedin_username,
+    _looks_like_instagram_url,
     apify_facebook_posts_scraper,
     apify_instagram_scraper,
     apify_linkedin_profile_detail,
@@ -161,6 +162,49 @@ def test_instagram_scraper_url_in_search_query(mock_apify_env, mock_apify_client
     assert "search" not in run_input
 
 
+@pytest.mark.parametrize(
+    "value",
+    [
+        "https://www.instagram.com/apify/",
+        "https://instagram.com/apify",
+        "http://instagram.com/explore/tags/cooking/",
+        "https://www.instagram.com/p/AbCdEfG/",
+    ],
+)
+def test_looks_like_instagram_url_true(value):
+    """Helper returns True for real Instagram URLs (with and without subdomain)."""
+    assert _looks_like_instagram_url(value) is True
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "apify",  # plain handle
+        "#cooking",  # hashtag
+        "why-instagram.com-matters",  # substring trap the old heuristic fell into
+        "http",  # bare scheme prefix the old heuristic accepted
+        "https://example.com/instagram.com",  # not actually hosted on instagram.com
+        "ftp://instagram.com/apify",  # wrong scheme
+        "javascript:alert(1)",
+        "",
+    ],
+)
+def test_looks_like_instagram_url_false(value):
+    """Helper rejects plain queries, lookalikes, and non-http(s) schemes."""
+    assert _looks_like_instagram_url(value) is False
+
+
+def test_instagram_scraper_search_query_with_instagram_substring(mock_apify_env, mock_apify_client):
+    """A search_query that merely contains 'instagram.com' is treated as a search, not a URL."""
+    with patch("strands_apify.utils.ApifyClient", return_value=mock_apify_client):
+        result = apify_instagram_scraper(search_query="why-instagram.com-matters")
+
+    assert result["status"] == "success"
+    run_input = mock_apify_client.actor.return_value.call.call_args.kwargs["run_input"]
+    assert run_input["search"] == "why-instagram.com-matters"
+    assert "directUrls" not in run_input
+
+
 def test_instagram_scraper_missing_params(mock_apify_env):
     """Instagram scraper returns error when neither search_query nor urls provided."""
     result = apify_instagram_scraper()